Logging

Log messages are emitted from each Step at different levels of importance. The levels used are the standard ones for Python (from least important to most important:

  1. DEBUG

  2. INFO

  3. WARNING

  4. ERROR

  5. CRITICAL

By default, only messages of type WARNING or higher are displayed. This can be controlled by providing a logging configuration file.

Logging configuration

A logging configuration file can be provided to customize what is logged.

A logging configuration file is searched for in the following places. The first one found is used in its entirety and all others are ignored:

  1. The file specified with the --logcfg option to the strun script.

  2. The file specified with the logcfg keyword to a .call() execution of a Step or Pipeline.

  3. A file called stpipe-log.cfg in the current working directory.

  4. ~/stpipe-log.cfg

  5. /etc/stpipe-log.cfg

The logging configuration file is in the standard ini-file format.

Each section name is a Unix-style filename glob pattern used to match a particular Step’s logger. The settings in that section apply only to that Steps that match that pattern. For example, to have the settings apply to all steps, create a section called [*]. To have the settings apply only to a Step called MyStep, create a section called [*.MyStep]. To apply settings to all Steps that are substeps of a step called MyStep, call the section [*.MyStep.*].

In each section, the following may be configured:

  1. level: The level at and above which logging messages will be displayed. May be one of (from least important to most important): DEBUG, INFO, WARNING, ERROR or CRITICAL.

  2. break_level: The level at and above which logging messages will cause an exception to be raised. For instance, if you would rather stop execution at the first ERROR message (rather than continue), set break_level to ERROR.

  3. handler: Defines where log messages are to be sent. By default, they are sent to stderr. However, one may also specify:

    • file:filename.log to send the log messages to the given file.

    • append:filename.log to append the log messages to the given file. This is useful over file if multiple processes may need to write to the same log file.

    • stdout to send log messages to stdout.

    Multiple handlers may be specified by putting the whole value in quotes and separating the entries with a comma.

  4. format: Allows one to customize what each log message contains. What this string may contain is described in the logging module LogRecord Attributes section of the Python standard library.

Examples

The following configuration turns on all log messages and saves them in the file myrun.log:

[*]
level = INFO
handler = file:myrun.log

In a scenario where the user is debugging a particular Step, they may want to hide all logging messages except for that Step, and stop when hitting any warning for that Step:

[*]
level = CRITICAL

[*.MyStep]
level = INFO
break_level = WARNING