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 meaning; 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.StreamHandler. When the interval 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’. An alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables.
dateformat (string) (default: %Y-%m-%dT%H:%M:%S)
level (ZConfig.components.logger.datatypes.logging_level) (default: notset)
path (string)
old-files (integer) (default: 0)
max-size (byte-size) (default: 0)
when (string)
interval (integer) (default: 0)
format (ZConfig.components.logger.handlers.log_format) (default: ——\n%(asctime)s %(levelname)s %(name)s %(message)s)

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’. An alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables.
dateformat (string) (default: %Y-%m-%dT%H:%M:%S)
level (ZConfig.components.logger.datatypes.logging_level) (default: notset)
facility (ZConfig.components.logger.handlers.syslog_facility) (default: user)
address (socket-address) (default: localhost:514)
format (ZConfig.components.logger.handlers.log_format) (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’. An alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables.
dateformat (string) (default: %Y-%m-%dT%H:%M:%S)
level (ZConfig.components.logger.datatypes.logging_level) (default: notset)
appname (string) (default: Zope)
format (ZConfig.components.logger.handlers.log_format) (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’. An alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables.
dateformat (string) (default: %Y-%m-%dT%H:%M:%S)
level (ZConfig.components.logger.datatypes.logging_level) (default: notset)
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.handlers.log_format) (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’. An alternative is ‘zope.exceptions.log.Formatter’, which enhances exception tracebacks with information from __traceback_info__ and __traceback_supplement__ variables.
dateformat (string) (default: %Y-%m-%dT%H:%M:%S)
level (ZConfig.components.logger.datatypes.logging_level) (default: notset)
from (string)
to (*) (string)
subject (string) (default: Message from Zope)
smtp-server (inet-address) (default: localhost)
smtp-username (string)
smtp-password (string)
format (ZConfig.components.logger.handlers.log_format) (default: %(asctime)s %(levelname)s %(name)s %(message)s)