(deep_dive_logging)=
# Logging

Logging in conda is based on the [Python logging framework](https://docs.python.org/3/library/logging.html).
In this guide, we'll describe the loggers and handlers used in conda, as well as how they are used.

## Logger hierarchy
Python logging uses loggers as the source of logging messages.
These loggers are organized as a single hierarchy defined by names given to individual loggers, with one nameless root logger.
Other logger names are given as dot separated strings, such that, for example, the logger named `a.b.c` has the parent `a.b`, which in turn has the parent `a`, which in turn has the root logger as its parent.
Python programs are free to use any name for loggers they like, but often the name will bear a relationship to the Python entity that is using it, most commonly there will be a module level logger, which is called `__name__`, i.e. `conda.<pkg>.<module>`, e.g. `conda.gateways.logging`.
This approach naturally arranges loggers used in a single code base into a hierarchy that follows the package structure.

```{mermaid}
:caption: The conda logger hierarchy. Dotted lines represent relations with `propagate = False`.

flowchart LR
    root["&lt;root&gt;"] -.-> conda
    conda --> modules["conda.&lt;pkg&gt;.&lt;module&gt;"]
    root --> auxlib
```

The full hierarchy of all module level loggers is given below at {ref}`full-module-loggers`.

### The root logger

The root logger is not used directly as a logging target, but it is used as a building block in the configuration of the logging system.

### The `conda` subhierarchy

The `conda` subhierarchy consists of all loggers whose name starts with `conda.` and it is mostly configured via the `conda` logger itself in {func}`conda.gateways.logging.initialize_logging`.

Historically, additional loggers were used for user-facing CLI text to stdout/stderr (`conda.stdout`, `conda.stderr`, `conda.stdoutlog`, `conda.stderrlog`, `conda.stdout.verbose`). They are **pending deprecation** (removal in 27.3) and are **no longer configured during normal CLI startup**. For new code, use `logging.getLogger(__name__)`.

### Other loggers

The `auxlib` logger a remnant from before the auxlib code was completely absorbed into conda.

## Potential effect on other loggers

There are three other functions that use {func}`logging.getLogger` and hence might affect other loggers. They are {func}`conda.gateways.logging.set_file_logging` that is never used in the code base and the context managers {func}`conda.common.io.disable_logger` and {func}`conda.common.io.stderr_log_level`, which are only used in testing.

## Root logger in auxlib

In {mod}`conda.auxlib.logz`, the root logger is modified.