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.

Conda largely follows this approach, however, it also makes use of some additional loggers.

flowchart LR root["&lt;root&gt;"] -.-> conda conda --> modules["conda.&lt;pkg&gt;.&lt;module&gt;"] conda -.-> conda.stdout -.-> conda.stdout.verbose conda -.-> conda.stderr conda -.-> conda.stdoutlog conda -.-> conda.stderrlog root --> auxlib root --> progress.update & progress.stop

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().

Additionally, the following five loggers are used for other output. These are likely to be replaced and should not be used in new code.

  • conda.stdout

  • conda.stderr

  • conda.stdoutlog

  • conda.stderrlog

  • conda.stdout.verbose

Other loggers#

Three more loggers appear in conda, namely progress.updateand progress.stop, which only appear in conda.plan.execute_actions, which in turn is deprecated (c.f. conda/conda#13881); and auxlib which likely is a remnant from before the auxlib code was completely absorbed into conda, since it only appears to be adorned with conda.auxlib.NullHandler in conda.auxlib.__init__.

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.