The configuration file format understood by fileConfig() is
based on ConfigParser functionality. The file must contain sections
called [loggers]
, [handlers]
and [formatters]
which identify by name the entities of each type which are defined in
the file. For each such entity, there is a separate section which
identified how that entity is configured. Thus, for a logger named
log01
in the [loggers]
section, the relevant
configuration details are held in a section
[logger_log01]
. Similarly, a handler called hand01
in
the [handlers]
section will have its configuration held in a
section called [handler_hand01]
, while a formatter called
form01
in the [formatters]
section will have its
configuration specified in a section called
[formatter_form01]
. The root logger configuration must be
specified in a section called [logger_root]
.
Examples of these sections in the file are given below.
[loggers] keys=root,log02,log03,log04,log05,log06,log07 [handlers] keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09 [formatters] keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
The root logger must specify a level and a list of handlers. An example of a root logger section is given below.
[logger_root] level=NOTSET handlers=hand01
The level
entry can be one of DEBUG, INFO, WARNING,
ERROR, CRITICAL
or NOTSET
. For the root logger only,
NOTSET
means that all messages will be logged. Level values are
eval()uated in the context of the logging
package's
namespace.
The handlers
entry is a comma-separated list of handler names,
which must appear in the [handlers]
section. These names must
appear in the [handlers]
section and have corresponding
sections in the configuration file.
For loggers other than the root logger, some additional information is required. This is illustrated by the following example.
[logger_parser] level=DEBUG handlers=hand01 propagate=1 qualname=compiler.parser
The level
and handlers
entries are interpreted as for
the root logger, except that if a non-root logger's level is specified
as NOTSET
, the system consults loggers higher up the hierarchy
to determine the effective level of the logger. The propagate
entry is set to 1 to indicate that messages must propagate to handlers
higher up the logger hierarchy from this logger, or 0 to indicate that
messages are not propagated to handlers up the hierarchy. The
qualname
entry is the hierarchical channel name of the logger,
that is to say the name used by the application to get the logger.
Sections which specify handler configuration are exemplified by the following.
[handler_hand01] class=StreamHandler level=NOTSET formatter=form01 args=(sys.stdout,)
The class
entry indicates the handler's class (as determined by
eval() in the logging
package's namespace). The
level
is interpreted as for loggers, and NOTSET
is taken
to mean "log everything".
The formatter
entry indicates the key name of the formatter for
this handler. If blank, a default formatter
(logging._defaultFormatter
) is used. If a name is specified, it
must appear in the [formatters]
section and have a
corresponding section in the configuration file.
The args
entry, when eval()uated in the context of
the logging
package's namespace, is the list of arguments to
the constructor for the handler class. Refer to the constructors for
the relevant handlers, or to the examples below, to see how typical
entries are constructed.
[handler_hand02] class=FileHandler level=DEBUG formatter=form02 args=('python.log', 'w') [handler_hand03] class=handlers.SocketHandler level=INFO formatter=form03 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT) [handler_hand04] class=handlers.DatagramHandler level=WARN formatter=form04 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT) [handler_hand05] class=handlers.SysLogHandler level=ERROR formatter=form05 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER) [handler_hand06] class=handlers.NTEventLogHandler level=CRITICAL formatter=form06 args=('Python Application', '', 'Application') [handler_hand07] class=handlers.SMTPHandler level=WARN formatter=form07 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject') [handler_hand08] class=handlers.MemoryHandler level=NOTSET formatter=form08 target= args=(10, ERROR) [handler_hand09] class=handlers.HTTPHandler level=NOTSET formatter=form09 args=('localhost:9022', '/log', 'GET')
Sections which specify formatter configuration are typified by the following.
[formatter_form01] format=F1 %(asctime)s %(levelname)s %(message)s datefmt=
The format
entry is the overall format string, and the
datefmt
entry is the strftime()-compatible date/time format
string. If empty, the package substitutes ISO8601 format date/times, which
is almost equivalent to specifying the date format string "The ISO8601 format also specifies milliseconds, which are appended to the
result of using the above format string, with a comma separator. An example
time in ISO8601 format is 2003-01-23 00:29:50,411
.