.. _cli_logging_options:

Controlling Log Output from Command-Line Tooling
================================================

Every command-line program has a standard set of options that control how logs are reported.
These can be listed using ``butler --help`` and are available to all command-line programs that :ref:`use the Butler command-line infrastructure <daf_butler_cli-other_commands>`.
The logging options must be given before any subcommand is specified.

By default the ``lsst`` log hierarchy is set to ``INFO`` logging level and the python root logger is left at its default level of ``WARNING``.
Additional loggers (and their descendants) can be treated the same as the default ``lsst`` logger by setting the ``$DAF_BUTLER_DEFAULT_LOGGER`` environment variable to a colon-separated list of logger names.

The logging level can be changed by using the ``--log-level`` command line option.
To change all the default loggers to ``DEBUG`` use ``--log-level DEBUG``.
The help text will list all the supported level names.
To change the logging level of the root python logger use either ``--log-level .=LEVEL`` (where ``LEVEL`` is the required level from the supported list).
Since the default logger is always set to ``INFO``, in order to set all loggers to, say, ``DEBUG`` then both the default and root logger must be set explicitly: ``--log-level "=DEBUG" --log-level DEBUG``.

This syntax demonstrates how to specify finer control of specific loggers.
For example to turn on debug logging solely in Butler datastores use ``--log-level lsst.daf.butler.datastores=DEBUG``.
The ``-log-level`` option can be given multiple times.

As an example of how the log options can be combined:

.. code-block:: bash

    butler --log-level lsst.daf.butler=DEBUG --long-log --log-label MY_ID --log-file log.json

These options will:

* set the ``lsst`` logger to ``INFO`` and the butler logger to ``DEBUG``, leaving all non-lsst loggers at ``WARNING``;
* generate formatted log messages that will use the long format that includes time stamps with every log message containing the special text ``MY_ID``;
* create a log file containing a JSON representation of the log messages.

The JSON output always includes every piece of information from the log record; the ``--long-log`` option has no effect on the content of the JSON file.