CliLog

class lsst.daf.butler.cli.cliLog.CliLog

Bases: object

Interface for managing python logging and lsst.log.

This class defines log format strings for the log output and timestamp formats. It also configures lsst.log to forward all messages to Python logging.

This class can perform log uninitialization, which allows command line interface code that initializes logging to run unit tests that execute in batches, without affecting other unit tests. See resetLog.

Attributes Summary

configState	Configuration state.
defaultLsstLogLevel
pylog_longLogFmt	The log format used when the lsst.log package is not importable and the log is initialized with longlog=True.
pylog_normalFmt	The log format used when the lsst.log package is not importable and the log is initialized with longlog=False.

Methods Summary

initLog(longlog, log_tty, log_file, …)	Initialize logging.
replayConfigState(configState)	Re-create configuration using configuration state recorded earlier.
resetLog()	Uninitialize the butler CLI Log handler and reset component log levels.
root_loggers()	Return the default root logger.
setLogLevels(logLevels, str]] | dict[str, …)	Set log level for one or more components or the root logger.

Attributes Documentation

configState = [(<bound method CliLog.initLog of <class 'lsst.daf.butler.cli.cliLog.CliLog'>>, False, True, (), None)]

Configuration state. Contains tuples where first item in a tuple is a method and remaining items are arguments for the method.

defaultLsstLogLevel = 50000

pylog_longLogFmt = '{levelname} {asctime} {name} ({MDC[LABEL]})({filename}:{lineno}) - {message}'

The log format used when the lsst.log package is not importable and the log is initialized with longlog=True.

pylog_normalFmt = '{name} {levelname}: {message}'

The log format used when the lsst.log package is not importable and the log is initialized with longlog=False.

Methods Documentation

classmethod initLog(longlog: bool, log_tty: bool = True, log_file: tuple = (), log_label: Optional[dict, None] = None) → None

Initialize logging. This should only be called once per program execution. After the first call this will log a warning and return.

If lsst.log is importable, will add its log handler to the python root logger’s handlers.

Parameters:

longlog : bool

If True, make log messages appear in long format, by default False.

log_tty : bool

Control whether a default stream handler is enabled that logs to the terminal.

log_file : tuple of str

Path to files to write log records. If path ends in .json the records will be written in JSON format. Else they will be written in text format. If empty no log file will be created. Records will be appended to this file if it exists.

log_label : dict of str

Keys and values to be stored in logging MDC for all JSON log records. Keys will be upper-cased.

classmethod replayConfigState(configState: list) → None

Re-create configuration using configuration state recorded earlier.

Parameters:

configState : list of tuple

Tuples contain a method as first item and arguments for the method, in the same format as cls.configState.

classmethod resetLog() → None

Uninitialize the butler CLI Log handler and reset component log levels.

If the lsst.log handler was added to the python root logger’s handlers in initLog, it will be removed here.

For each logger level that was set by this class, sets that logger’s level to the value it was before this class set it. For lsst.log, if a component level was uninitialized, it will be set to Log.defaultLsstLogLevel because there is no log4cxx api to set a component back to an uninitialized state.

static root_loggers() → set

Return the default root logger.

Returns:

log_name : set of str

The name(s) of the root logger(s) to use when the log level is being set without a log name being specified.

Notes

The default is lsst (which controls the butler infrastructure) but additional loggers can be specified by setting the environment variable DAF_BUTLER_ROOT_LOGGER. This variable can contain multiple default loggers separated by a :.

classmethod setLogLevels(logLevels: list[tuple[str | None, str]] | dict[str, str][list, dict]) → None

Set log level for one or more components or the root logger.

Parameters:

logLevels : list of tuple

per-component logging levels, each item in the list is a tuple (component, level), component is a logger name or an empty string or None for default root logger, level is a logging level name, one of CRITICAL, ERROR, WARNING, INFO, DEBUG (case insensitive).

Notes

The special name . can be used to set the Python root logger.