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
through50
(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
, orsafe-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 astyle
ofsafe-template
.- path (string)
Path of the log file to write.
Specifying
STDOUT
orSTDERR
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 to1
.If
when
is not specified, it is an error to specifyinterval
.- 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, unlessarbitrary-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
orSTDERR
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
orSTDERR
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
through50
(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
, orsafe-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 astyle
ofsafe-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
through50
(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
, orsafe-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 astyle
ofsafe-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
through50
(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
, orsafe-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 astyle
ofsafe-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
through50
(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
, orsafe-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 astyle
ofsafe-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 astext/plain
.