Logging#

Logging in conda is based on the Python logging framework. 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.

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

The conda logger hierarchy. Dotted lines represent relations with propagate = False.#

The full hierarchy of all module level loggers is given below at 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 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 logging.getLogger() and hence might affect other loggers. They are conda.gateways.logging.set_file_logging() that is never used in the code base and the context managers conda.common.io.disable_logger() and conda.common.io.stderr_log_level(), which are only used in testing.

Root logger in auxlib#

In conda.auxlib.logz, the root logger is modified.