Add some docs on logging options

doc/lsst.daf.butler/index.rst

@@ -70,6 +70,7 @@ Butler Command-Line Reference
    :maxdepth: 1
 
    scripts/options-file.rst
+   scripts/logging.rst
    scripts/butler
 
 .. _lsst.daf.butler-dev:

doc/lsst.daf.butler/scripts/logging.rst

@@ -0,0 +1,35 @@
+.. _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 root loggers can be treated as the default loggers by setting the ``$DAF_BUTLER_ROOT_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"`` or ``--log-level __root__=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``;
+* generate formatted log messages that will use the long format that includes time stamps with every log message containing the special text ``MY_ID``;
+* Will 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.

doc/lsst.daf.butler/writing-subcommands.rst

@@ -413,6 +413,8 @@ The settings for ``obs_base`` are like this:
 
     envPrepend(DAF_BUTLER_PLUGINS, $OBS_BASE_DIR/python/lsst/obs/base/cli/resources.yaml)
 
+.. _daf_butler_cli-other_commands:
+
 Writing Other Commands
 ======================