Configuring Logging

One common use of ZConfig is to configure the Python logging framework. ZConfig provides one simple convenience function to do this:

ZConfig.configureLoggers(text): Configure one or more loggers from configuration text.

Suppose we have the following logging configuration in a file called simple-root-config.conf:

<logger>
    level INFO
    <logfile>
       path STDOUT
       format %(levelname)s %(name)s %(message)s
    </logfile>
</logger>

We can load this file and pass its contents to configureLoggers:

from ZConfig import configureLoggers
with open('simple-root-config.conf') as f:
    configureLoggers(f.read())

When this returns, the root logger is configured to output messages logged at INFO or above to the console, as we can see in the following example:

>>> from logging import getLogger
>>> getLogger().info('We see an info message')
INFO root We see an info message
>>> getLogger().debug('We do not see a debug message')

A more common configuration would see STDOUT replaced with a path to the file into which log entries would be written.

Although loading configuration from a file is common, we could of course also pass a string literal to configureLoggers(). Any type of Python string (bytes or unicode) is acceptable.

Configuration Format

The configuration text is in the ZConfig format and supports comments and substitutions.

It can contain multiple <logger> elements, each of which can have any number of handler elements.

<logger> (ZConfig.components.logger.logger.LoggerFactory)

level (ZConfig.components.logger.datatypes.logging_level) (default: info)

Verbosity setting for the logger. Values must be a name of a level, or an integer in the range [0..50]. The names of the levels, in order of increasing verbosity (names on the same line are equivalent):

critical, fatal
error
warn, warning
info
blather
debug
trace
all

The special name “notset”, or the numeric value 0, indicates that the setting for the parent logger should be used.

It is strongly recommended that names be used rather than numeric values to ensure that configuration files can be deciphered more easily.

zconfig.logger.handler*

Handlers to install on this logger. Each handler describes how logging events should be presented.

propagate (boolean) (default: true)

Indicates whether events that reach this logger should be propogated toward the root of the logger hierarchy. If true (the default), events will be passed to the logger’s parent after being handled. If false, events will be handled and the parent will not be informed. There is not a way to control propogation by the severity of the event.

name (dotted-name)

The dotted name of the logger. This give it a location in the logging hierarchy. Most applications provide a specific set of subsystem names for which logging is meaningful; consult the application documentation for the set of names that are actually interesting for the application.

Examples

Here’s the configuration we looked at above. It configures the root (unnamed) logger with one handler (<logfile>), operating at the INFO level:

<logger>
    level INFO
    <logfile>
       path STDOUT
       format %(levelname)s %(name)s %(message)s
    </logfile>
</logger>

We can configure a different logger in the hierarchy to use the DEBUG level at the same time as we configure the root logger. We’re not specifying a handler for it, but the default propagate value will let the lower level logger use the root logger’s handler:

<logger>
    level INFO
    <logfile>
       path STDOUT
       format %(levelname)s %(name)s %(message)s
    </logfile>
</logger>
<logger>
    name my.package
    level DEBUG
</logger>

If we load that configuration from root-and-child-config.conf, we can expect this behaviour:

>>> with open('root-and-child-config.conf') as f:
...     configureLoggers(f.read())
>>> getLogger().info('Here is another info message')
INFO root Here is another info message
>>> getLogger().debug('This debug message is hidden')
>>> getLogger('my.package').debug('The debug message for my.package shows')
DEBUG my.package The debug message for my.package shows

Log Handlers

Many of Python’s built-in log handlers can be configured with ZConfig.

Files

The <logfile> handler writes to files or standard output or standard error (when the path is STDOUT or STDERR respectively). It configures a logging.FileHandler or logging.StreamHandler. When the when or max-size attributes are set, the files on disk will be rotated either at set intervals or when files reach the set size, respectively.

<logfile> (ZConfig.components.logger.handlers.FileHandlerFactory)

Example:

<logfile>
    path STDOUT
    format %(name)s %(message)s
</logfile>

formatter (dotted-name)

Logging formatter class.

The default is logging.Formatter.

One alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables from each stack frame.

dateformat (string) (default: %Y-%m-%dT%H:%M:%S)

Timestamp format used for the ‘asctime’ field.

This is used with Python’s time.strftime() function, so must be compatible with that function on the host platform.

level (ZConfig.components.logger.datatypes.logging_level) (default: notset)

Output level for the log handler.

Python standard logging levels are supported by name (case-insensitive), as are the following additional names:

all (level 1)
trace (level 5)
blather (level 15)

These additional level names are not defined using logging.addLevelName(), though an application may do so.

Numeric values 0 through 50 (inclusive) are permitted.

style (ZConfig.components.logger.formatter.log_format_style) (default: classic)

Replacement mechanism to use with the format string.

The value must be one of classic (the default), format, template, or safe-template.

arbitrary-fields (boolean) (default: false)

If true, allow arbitrary fields in the log record object to be referenced from the format value.

This does not cause references to fields not present in the log record to be accepted; it only means unknown fields will not cause configuration of the formatter to be denied.

To get both effects, set this to true and use a style of safe-template.

path (string)

Path of the log file to write.

Specifying STDOUT or STDERR will cause the appropriate standard stream to be used instead of a file. In these cases, rotation, encoding, and delayed opening are not available, and will be considered configuration errors.

old-files (integer) (default: 0)

Number of old log files which will be retained when rotation is configured.

This must be set to a positive integer if rotation is configured. An error is generated if rotation is requested without setting old-files.

max-size (byte-size) (default: 0)

Target maximum size for a logfile; once a logfile reaches the maximum size, it will be rotated.

when (string)

Specification for specific time at which rotation should occur.

Allowed values are described for logging.handlers.TimedRotatingFileHandler; this value is passed through to the underlying handler.

interval (integer) (default: 0)

Frequency of rotation at the time specified by when.

If not specified, but when is specified, this will default to 1.

If when is not specified, it is an error to specify interval.

format (ZConfig.components.logger.formatter.escaped_string) (default: ——\n%(asctime)s %(levelname)s %(name)s %(message)s)

Format string for log entries. This value is used to create an instance of the class identified by formatter.

The following escape characters are supported with the same replacements as in Python string literals:

\b  \f  \n  \r  \t

Field placeholders are checked to refer to the fields available in the logging.LogRecord instances created without extra fields. Referring to other fields will generate an error in loading the configuration, unless arbitrary-fields is true.

encoding (string)

Encoding for the underlying file.

If not specified, Python’s default encoding handling is used.

This cannot be specified for STDOUT or STDERR destinations, and must be omitted in such cases.

delay (boolean) (default: false)

If true, opening of the log file will be delayed until a message is emitted. This avoids creating logfiles that may only be written to rarely or under special conditions.

This cannot be specified for STDOUT or STDERR destinations, and must be omitted in such cases.

The System Log

The <syslog> handler configures the logging.handlers.SysLogHandler.

<syslog> (ZConfig.components.logger.handlers.SyslogHandlerFactory)

formatter (dotted-name)

Logging formatter class.

The default is logging.Formatter.

One alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables from each stack frame.

dateformat (string) (default: %Y-%m-%dT%H:%M:%S)

Timestamp format used for the ‘asctime’ field.

This is used with Python’s time.strftime() function, so must be compatible with that function on the host platform.

level (ZConfig.components.logger.datatypes.logging_level) (default: notset)

Output level for the log handler.

Python standard logging levels are supported by name (case-insensitive), as are the following additional names:

all (level 1)
trace (level 5)
blather (level 15)

These additional level names are not defined using logging.addLevelName(), though an application may do so.

Numeric values 0 through 50 (inclusive) are permitted.

style (ZConfig.components.logger.formatter.log_format_style) (default: classic)

Replacement mechanism to use with the format string.

The value must be one of classic (the default), format, template, or safe-template.

arbitrary-fields (boolean) (default: false)

If true, allow arbitrary fields in the log record object to be referenced from the format value.

This does not cause references to fields not present in the log record to be accepted; it only means unknown fields will not cause configuration of the formatter to be denied.

To get both effects, set this to true and use a style of safe-template.

facility (ZConfig.components.logger.handlers.syslog_facility) (default: user)

address (socket-address) (default: localhost:514)

format (ZConfig.components.logger.formatter.escaped_string) (default: %(name)s %(message)s)

Windows Event Log

On Windows, the <win32-eventlog> configures the logging.handlers.NTEventLogHandler.

<win32-eventlog> (ZConfig.components.logger.handlers.Win32EventLogFactory)

formatter (dotted-name)

Logging formatter class.

The default is logging.Formatter.

One alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables from each stack frame.

dateformat (string) (default: %Y-%m-%dT%H:%M:%S)

Timestamp format used for the ‘asctime’ field.

This is used with Python’s time.strftime() function, so must be compatible with that function on the host platform.

level (ZConfig.components.logger.datatypes.logging_level) (default: notset)

Output level for the log handler.

Python standard logging levels are supported by name (case-insensitive), as are the following additional names:

all (level 1)
trace (level 5)
blather (level 15)

These additional level names are not defined using logging.addLevelName(), though an application may do so.

Numeric values 0 through 50 (inclusive) are permitted.

style (ZConfig.components.logger.formatter.log_format_style) (default: classic)

Replacement mechanism to use with the format string.

The value must be one of classic (the default), format, template, or safe-template.

arbitrary-fields (boolean) (default: false)

If true, allow arbitrary fields in the log record object to be referenced from the format value.

This does not cause references to fields not present in the log record to be accepted; it only means unknown fields will not cause configuration of the formatter to be denied.

To get both effects, set this to true and use a style of safe-template.

appname (string) (default: Zope)

format (ZConfig.components.logger.formatter.escaped_string) (default: %(levelname)s %(name)s %(message)s)

HTTP

The <<http-logger> element configures logging.handlers.HTTPHandler.

<http-logger> (ZConfig.components.logger.handlers.HTTPHandlerFactory)

formatter (dotted-name)

Logging formatter class.

The default is logging.Formatter.

One alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables from each stack frame.

dateformat (string) (default: %Y-%m-%dT%H:%M:%S)

Timestamp format used for the ‘asctime’ field.

This is used with Python’s time.strftime() function, so must be compatible with that function on the host platform.

level (ZConfig.components.logger.datatypes.logging_level) (default: notset)

Output level for the log handler.

Python standard logging levels are supported by name (case-insensitive), as are the following additional names:

all (level 1)
trace (level 5)
blather (level 15)

These additional level names are not defined using logging.addLevelName(), though an application may do so.

Numeric values 0 through 50 (inclusive) are permitted.

style (ZConfig.components.logger.formatter.log_format_style) (default: classic)

Replacement mechanism to use with the format string.

The value must be one of classic (the default), format, template, or safe-template.

arbitrary-fields (boolean) (default: false)

If true, allow arbitrary fields in the log record object to be referenced from the format value.

This does not cause references to fields not present in the log record to be accepted; it only means unknown fields will not cause configuration of the formatter to be denied.

To get both effects, set this to true and use a style of safe-template.

url (ZConfig.components.logger.handlers.http_handler_url) (default: http://localhost/)

method (ZConfig.components.logger.handlers.get_or_post) (default: GET)

format (ZConfig.components.logger.formatter.escaped_string) (default: %(asctime)s %(levelname)s %(name)s %(message)s)

Email

ZConfig has support for Python’s logging.handlers.SMTPHandler via the <email-notifier> handler.

<email-notifier> (ZConfig.components.logger.handlers.SMTPHandlerFactory)

Example:

<email-notifier>
  to sysadmin@example.com
  to john@example.com
  from zlog-user@example.com
  level fatal
  smtp-username john
  smtp-password johnpw
</email-notifier>

formatter (dotted-name)

Logging formatter class.

The default is logging.Formatter.

One alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables from each stack frame.

dateformat (string) (default: %Y-%m-%dT%H:%M:%S)

Timestamp format used for the ‘asctime’ field.

This is used with Python’s time.strftime() function, so must be compatible with that function on the host platform.

level (ZConfig.components.logger.datatypes.logging_level) (default: notset)

Output level for the log handler.

Python standard logging levels are supported by name (case-insensitive), as are the following additional names:

all (level 1)
trace (level 5)
blather (level 15)

These additional level names are not defined using logging.addLevelName(), though an application may do so.

Numeric values 0 through 50 (inclusive) are permitted.

style (ZConfig.components.logger.formatter.log_format_style) (default: classic)

Replacement mechanism to use with the format string.

The value must be one of classic (the default), format, template, or safe-template.

arbitrary-fields (boolean) (default: false)

If true, allow arbitrary fields in the log record object to be referenced from the format value.

This does not cause references to fields not present in the log record to be accepted; it only means unknown fields will not cause configuration of the formatter to be denied.

To get both effects, set this to true and use a style of safe-template.

from (string)

to (*) (string)

subject (string) (default: Message from Zope)

smtp-server (inet-address) (default: localhost)

smtp-username (string)

User name to use for SMTP authentication. This can only be specified if smtp-password is also specified.

smtp-password (string)

Password to use for SMTP authentication. This can only be specified if smtp-username is also specified.

format (ZConfig.components.logger.formatter.escaped_string) (default: %(asctime)s %(levelname)s %(name)s %(message)s)

Format string for the email content.

The following escape characters are supported with the same replacements as in Python string literals:

\b  \f  \n  \r  \t

%-replacements are checked to refer to the fields available in the logging.LogRecord instances created without extra fields. Referring to other fields will generate an error in loading the configuration.

Emails will be sent without a Content-Type header, so the content will be interpreted as text/plain.