logging.config —- 日志记录配置

源代码：Lib/logging/config.py

Important

此页面仅包含参考信息。有关教程，请参阅

• 基础教程

• 进阶教程

• 日志操作手册

This section describes the API for configuring the logging module.

Configuration functions

The following functions configure the logging module. They are located in thelogging.config module. Their use is optional —- you can configure thelogging module using these functions or by making calls to the main API (definedin logging itself) and defining handlers which are declared either inlogging or logging.handlers.

• logging.config.dictConfig(config)

Takes the logging configuration from a dictionary. The contents ofthis dictionary are described in Configuration dictionary schemabelow.

If an error is encountered during configuration, this function willraise a ValueError, TypeError, AttributeErroror ImportError with a suitably descriptive message. Thefollowing is a (possibly incomplete) list of conditions which willraise an error:

• A level which is not a string or which is a string notcorresponding to an actual logging level.

• A propagate value which is not a boolean.

• An id which does not have a corresponding destination.

• A non-existent handler id found during an incremental call.

• An invalid logger name.

• Inability to resolve to an internal or external object.

Parsing is performed by the DictConfigurator class, whoseconstructor is passed the dictionary used for configuration, andhas a configure() method. The logging.config modulehas a callable attribute dictConfigClasswhich is initially set to DictConfigurator.You can replace the value of dictConfigClass with asuitable implementation of your own.

dictConfig() calls dictConfigClass passingthe specified dictionary, and then calls the configure() method onthe returned object to put the configuration into effect:

def dictConfig(config):    dictConfigClass(config).configure()

For example, a subclass of DictConfigurator could callDictConfigurator.init() in its own init(), thenset up custom prefixes which would be usable in the subsequentconfigure() call. dictConfigClass would be bound tothis new subclass, and then dictConfig() could be called exactly asin the default, uncustomized state.

3.2 新版功能.

• logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)

• Reads the logging configuration from a configparser-format file. Theformat of the file should be as described inConfiguration file format.This function can be called several times from an application, allowing anend user to select from various pre-canned configurations (if the developerprovides a mechanism to present the choices and load the chosenconfiguration).

  • 参数

  • • fname — A filename, or a file-like object, or an instance derivedfrom RawConfigParser. If aRawConfigParser-derived instance is passed, it is used asis. Otherwise, a Configparser isinstantiated, and the configuration read by it from theobject passed in fname. If that has a readline()method, it is assumed to be a file-like object and read usingread_file(); otherwise,it is assumed to be a filename and passed toread().

    • defaults — Defaults to be passed to the ConfigParser can be specifiedin this argument.

    • disable_existing_loggers — If specified as False, loggers whichexist when this call is made are leftenabled. The default is True because thisenables old behaviour in abackward-compatible way. This behaviour is todisable any existing non-root loggers unlessthey or their ancestors are explicitly namedin the logging configuration.

在 3.4 版更改: An instance of a subclass of RawConfigParser isnow accepted as a value for fname. This facilitates:

• Use of a configuration file where logging configuration is just partof the overall application configuration.

• Use of a configuration read from a file, and then modified by the usingapplication (e.g. based on command-line parameters or other aspectsof the runtime environment) before being passed to fileConfig.

• logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)
• Starts up a socket server on the specified port, and listens for newconfigurations. If no port is specified, the module's defaultDEFAULT_LOGGING_CONFIG_PORT is used. Logging configurations will besent as a file suitable for processing by dictConfig() orfileConfig(). Returns a Thread instance on whichyou can call start() to start the server, and whichyou can join() when appropriate. To stop the server,call stopListening().

The verify argument, if specified, should be a callable which shouldverify whether bytes received across the socket are valid and should beprocessed. This could be done by encrypting and/or signing what is sentacross the socket, such that the verify callable can performsignature verification and/or decryption. The verify callable is calledwith a single argument - the bytes received across the socket - and shouldreturn the bytes to be processed, or None to indicate that the bytes shouldbe discarded. The returned bytes could be the same as the passed in bytes(e.g. when only verification is done), or they could be completely different(perhaps if decryption were performed).

To send a configuration to the socket, read in the configuration file andsend it to the socket as a sequence of bytes preceded by a four-byte lengthstring packed in binary using struct.pack('>L', n).

注解

Because portions of the configuration are passed througheval(), use of this function may open its users to a security risk.While the function only binds to a socket on localhost, and so doesnot accept connections from remote machines, there are scenarios whereuntrusted code could be run under the account of the process which callslisten(). Specifically, if the process calling listen() runson a multi-user machine where users cannot trust each other, then amalicious user could arrange to run essentially arbitrary code in avictim user's process, simply by connecting to the victim'slisten() socket and sending a configuration which runs whatevercode the attacker wants to have executed in the victim's process. This isespecially easy to do if the default port is used, but not hard even if adifferent port is used). To avoid the risk of this happening, use theverify argument to listen() to prevent unrecognisedconfigurations from being applied.

在 3.4 版更改: The verify argument was added.

注解

If you want to send configurations to the listener which don'tdisable existing loggers, you will need to use a JSON format forthe configuration, which will use dictConfig() for configuration.This method allows you to specify disable_existing_loggers asFalse in the configuration you send.

• logging.config.stopListening()
• Stops the listening server which was created with a call to listen().This is typically called before calling join() on the return value fromlisten().

Configuration dictionary schema

Describing a logging configuration requires listing the variousobjects to create and the connections between them; for example, youmay create a handler named 'console' and then say that the loggernamed 'startup' will send its messages to the 'console' handler.These objects aren't limited to those provided by the loggingmodule because you might write your own formatter or handler class.The parameters to these classes may also need to include externalobjects such as sys.stderr. The syntax for describing theseobjects and connections is defined in Object connectionsbelow.

Dictionary Schema Details

The dictionary passed to dictConfig() must contain the followingkeys:

• version - to be set to an integer value representing the schemaversion. The only valid value at present is 1, but having this keyallows the schema to evolve while still preserving backwardscompatibility.

All other keys are optional, but if present they will be interpretedas described below. In all cases below where a 'configuring dict' ismentioned, it will be checked for the special '()' key to see if acustom instantiation is required. If so, the mechanism described inUser-defined objects below is used to create an instance;otherwise, the context is used to determine what to instantiate.

• formatters - the corresponding value will be a dict in which eachkey is a formatter id and each value is a dict describing how toconfigure the corresponding Formatter instance.

The configuring dict is searched for keys format and datefmt(with defaults of None) and these are used to construct aFormatter instance.

在 3.8 版更改: a validate key (with default of True) can be added intothe formatters section of the configuring dict, this is tovalidate the format.

• filters - the corresponding value will be a dict in which each keyis a filter id and each value is a dict describing how to configurethe corresponding Filter instance.

The configuring dict is searched for the key name (defaulting to theempty string) and this is used to construct a logging.Filterinstance.

• handlers - the corresponding value will be a dict in which eachkey is a handler id and each value is a dict describing how toconfigure the corresponding Handler instance.

The configuring dict is searched for the following keys:

• class (mandatory). This is the fully qualified name of thehandler class.

• level (optional). The level of the handler.

• formatter (optional). The id of the formatter for thishandler.

• filters (optional). A list of ids of the filters for thishandler.

All other keys are passed through as keyword arguments to thehandler's constructor. For example, given the snippet:

handlers:
  console:
    class : logging.StreamHandler
    formatter: brief
    level   : INFO
    filters: [allow_foo]
    stream  : ext://sys.stdout
  file:
    class : logging.handlers.RotatingFileHandler
    formatter: precise
    filename: logconfig.log
    maxBytes: 1024
    backupCount: 3

the handler with id console is instantiated as alogging.StreamHandler, using sys.stdout as the underlyingstream. The handler with id file is instantiated as alogging.handlers.RotatingFileHandler with the keyword argumentsfilename='logconfig.log', maxBytes=1024, backupCount=3.

• loggers - the corresponding value will be a dict in which each keyis a logger name and each value is a dict describing how toconfigure the corresponding Logger instance.

The configuring dict is searched for the following keys:

• level (optional). The level of the logger.

• propagate (optional). The propagation setting of the logger.

• filters (optional). A list of ids of the filters for thislogger.

• handlers (optional). A list of ids of the handlers for thislogger.

The specified loggers will be configured according to the level,propagation, filters and handlers specified.

• root - this will be the configuration for the root logger.Processing of the configuration will be as for any logger, exceptthat the propagate setting will not be applicable.

• incremental - whether the configuration is to be interpreted asincremental to the existing configuration. This value defaults toFalse, which means that the specified configuration replaces theexisting configuration with the same semantics as used by theexisting fileConfig() API.

If the specified value is True, the configuration is processedas described in the section on Incremental Configuration.

• disable_existing_loggers - whether any existing non-root loggers areto be disabled. This setting mirrors the parameter of the same name infileConfig(). If absent, this parameter defaults to True.This value is ignored if incremental is True.

Incremental Configuration

It is difficult to provide complete flexibility for incrementalconfiguration. For example, because objects such as filtersand formatters are anonymous, once a configuration is set up, it isnot possible to refer to such anonymous objects when augmenting aconfiguration.

Furthermore, there is not a compelling case for arbitrarily alteringthe object graph of loggers, handlers, filters, formatters atrun-time, once a configuration is set up; the verbosity of loggers andhandlers can be controlled just by setting levels (and, in the case ofloggers, propagation flags). Changing the object graph arbitrarily ina safe way is problematic in a multi-threaded environment; while notimpossible, the benefits are not worth the complexity it adds to theimplementation.

Thus, when the incremental key of a configuration dict is presentand is True, the system will completely ignore any formatters andfilters entries, and process only the levelsettings in the handlers entries, and the level andpropagate settings in the loggers and root entries.

Using a value in the configuration dict lets configurations to be sentover the wire as pickled dicts to a socket listener. Thus, the loggingverbosity of a long-running application can be altered over time withno need to stop and restart the application.

Object connections

The schema describes a set of logging objects - loggers,handlers, formatters, filters - which are connected to each other inan object graph. Thus, the schema needs to represent connectionsbetween the objects. For example, say that, once configured, aparticular logger has attached to it a particular handler. For thepurposes of this discussion, we can say that the logger represents thesource, and the handler the destination, of a connection between thetwo. Of course in the configured objects this is represented by thelogger holding a reference to the handler. In the configuration dict,this is done by giving each destination object an id which identifiesit unambiguously, and then using the id in the source object'sconfiguration to indicate that a connection exists between the sourceand the destination object with that id.

So, for example, consider the following YAML snippet:

formatters:
  brief:
    # configuration for formatter with id 'brief' goes here
  precise:
    # configuration for formatter with id 'precise' goes here
handlers:
  h1: #This is an id
   # configuration of handler with id 'h1' goes here
   formatter: brief
  h2: #This is another id
   # configuration of handler with id 'h2' goes here
   formatter: precise
loggers:
  foo.bar.baz:
    # other configuration for logger 'foo.bar.baz'
    handlers: [h1, h2]

(Note: YAML used here because it's a little more readable than theequivalent Python source form for the dictionary.)

The ids for loggers are the logger names which would be usedprogrammatically to obtain a reference to those loggers, e.g.foo.bar.baz. The ids for Formatters and Filters can be any stringvalue (such as brief, precise above) and they are transient,in that they are only meaningful for processing the configurationdictionary and used to determine connections between objects, and arenot persisted anywhere when the configuration call is complete.

The above snippet indicates that logger named foo.bar.baz shouldhave two handlers attached to it, which are described by the handlerids h1 and h2. The formatter for h1 is that described by idbrief, and the formatter for h2 is that described by idprecise.

User-defined objects

The schema supports user-defined objects for handlers, filters andformatters. (Loggers do not need to have different types fordifferent instances, so there is no support in this configurationschema for user-defined logger classes.)

Objects to be configured are described by dictionarieswhich detail their configuration. In some places, the logging systemwill be able to infer from the context how an object is to beinstantiated, but when a user-defined object is to be instantiated,the system will not know how to do this. In order to provide completeflexibility for user-defined object instantiation, the user needsto provide a 'factory' - a callable which is called with aconfiguration dictionary and which returns the instantiated object.This is signalled by an absolute import path to the factory beingmade available under the special key '()'. Here's a concreteexample:

formatters:
  brief:
    format: '%(message)s'
  default:
    format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
    datefmt: '%Y-%m-%d %H:%M:%S'
  custom:
      (): my.package.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42

The above YAML snippet defines three formatters. The first, with idbrief, is a standard logging.Formatter instance with thespecified format string. The second, with id default, has alonger format and also defines the time format explicitly, and willresult in a logging.Formatter initialized with those two formatstrings. Shown in Python source form, the brief and defaultformatters have configuration sub-dictionaries:

{
  'format' : '%(message)s'
}

和:

{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
}

respectively, and as these dictionaries do not contain the special key'()', the instantiation is inferred from the context: as a result,standard logging.Formatter instances are created. Theconfiguration sub-dictionary for the third formatter, with idcustom, is:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
}

and this contains the special key '()', which means thatuser-defined instantiation is wanted. In this case, the specifiedfactory callable will be used. If it is an actual callable it will beused directly - otherwise, if you specify a string (as in the example)the actual callable will be located using normal import mechanisms.The callable will be called with the remaining items in theconfiguration sub-dictionary as keyword arguments. In the aboveexample, the formatter with id custom will be assumed to bereturned by the call:

my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)

The key '()' has been used as the special key because it is not avalid keyword parameter name, and so will not clash with the names ofthe keyword arguments used in the call. The '()' also serves as amnemonic that the corresponding value is a callable.

Access to external objects

There are times where a configuration needs to refer to objectsexternal to the configuration, for example sys.stderr. If theconfiguration dict is constructed using Python code, this isstraightforward, but a problem arises when the configuration isprovided via a text file (e.g. JSON, YAML). In a text file, there isno standard way to distinguish sys.stderr from the literal string'sys.stderr'. To facilitate this distinction, the configurationsystem looks for certain special prefixes in string values andtreat them specially. For example, if the literal string'ext://sys.stderr' is provided as a value in the configuration,then the ext:// will be stripped off and the remainder of thevalue processed using normal import mechanisms.

The handling of such prefixes is done in a way analogous to protocolhandling: there is a generic mechanism to look for prefixes whichmatch the regular expression ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$whereby, if the prefix is recognised, the suffix is processedin a prefix-dependent manner and the result of the processing replacesthe string value. If the prefix is not recognised, then the stringvalue will be left as-is.

Access to internal objects

As well as external objects, there is sometimes also a need to referto objects in the configuration. This will be done implicitly by theconfiguration system for things that it knows about. For example, thestring value 'DEBUG' for a level in a logger or handler willautomatically be converted to the value logging.DEBUG, and thehandlers, filters and formatter entries will take anobject id and resolve to the appropriate destination object.

However, a more generic mechanism is needed for user-definedobjects which are not known to the logging module. Forexample, consider logging.handlers.MemoryHandler, which takesa target argument which is another handler to delegate to. Sincethe system already knows about this class, then in the configuration,the given target just needs to be the object id of the relevanttarget handler, and the system will resolve to the handler from theid. If, however, a user defines a my.package.MyHandler which hasan alternate handler, the configuration system would not know thatthe alternate referred to a handler. To cater for this, a genericresolution system allows the user to specify:

handlers:
  file:
    # configuration of file handler goes here
 
  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

The literal string 'cfg://handlers.file' will be resolved in ananalogous way to strings with the ext:// prefix, but lookingin the configuration itself rather than the import namespace. Themechanism allows access by dot or by index, in a similar way tothat provided by str.format. Thus, given the following snippet:

handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@domain.tld
    toaddrs:
      - support_team@domain.tld
      - dev_team@domain.tld
    subject: Houston, we have a problem.

in the configuration, the string 'cfg://handlers' would resolve tothe dict with key handlers, the string 'cfg://handlers.emailwould resolve to the dict with key email in the handlers dict,and so on. The string 'cfg://handlers.email.toaddrs[1] wouldresolve to 'dev_team.domain.tld' and the string'cfg://handlers.email.toaddrs[0]' would resolve to the value'support_team@domain.tld'. The subject value could be accessedusing either 'cfg://handlers.email.subject' or, equivalently,'cfg://handlers.email[subject]'. The latter form only needs to beused if the key contains spaces or non-alphanumeric characters. If anindex value consists only of decimal digits, access will be attemptedusing the corresponding integer value, falling back to the stringvalue if needed.

Given a string cfg://handlers.myhandler.mykey.123, this willresolve to config_dict['handlers']['myhandler']['mykey']['123'].If the string is specified as cfg://handlers.myhandler.mykey[123],the system will attempt to retrieve the value fromconfig_dict['handlers']['myhandler']['mykey'][123], and fall backto config_dict['handlers']['myhandler']['mykey']['123'] if thatfails.

Import resolution and custom importers

Import resolution, by default, uses the builtin import() functionto do its importing. You may want to replace this with your own importingmechanism: if so, you can replace the importer attribute of theDictConfigurator or its superclass, theBaseConfigurator class. However, you need to becareful because of the way functions are accessed from classes viadescriptors. If you are using a Python callable to do your imports, and youwant to define it at class level rather than instance level, you need to wrapit with staticmethod(). For example:

from importlib import import_module
from logging.config import BaseConfigurator
 
BaseConfigurator.importer = staticmethod(import_module)

You don't need to wrap with staticmethod() if you're setting the importcallable on a configurator instance.

Configuration file format

The configuration file format understood by fileConfig() is based onconfigparser functionality. The file must contain sections called[loggers], [handlers] and [formatters] which identify by name theentities of each type which are defined in the file. For each such entity, thereis a separate section which identifies how that entity is configured. Thus, fora logger named log01 in the [loggers] section, the relevantconfiguration details are held in a section [logger_log01]. Similarly, ahandler called hand01 in the [handlers] section will have itsconfiguration held in a section called [handler_hand01], while a formattercalled form01 in the [formatters] section will have its configurationspecified in a section called [formatter_form01]. The root loggerconfiguration must be specified in a section called [logger_root].

注解

The fileConfig() API is older than the dictConfig() API and doesnot provide functionality to cover certain aspects of logging. For example,you cannot configure Filter objects, which provide forfiltering of messages beyond simple integer levels, using fileConfig().If you need to have instances of Filter in your loggingconfiguration, you will need to use dictConfig(). Note that futureenhancements to configuration functionality will be added todictConfig(), so it's worth considering transitioning to this newerAPI when it's convenient to do so.

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 aroot logger section is given below.

[logger_root]
level=NOTSET
handlers=hand01

The level entry can be one of DEBUG, INFO, WARNING, ERROR, CRITICAL orNOTSET. For the root logger only, NOTSET means that all messages will belogged. Level values are eval()uated in the context of the loggingpackage's namespace.

The handlers entry is a comma-separated list of handler names, which mustappear in the [handlers] section. These names must appear in the[handlers] section and have corresponding sections in the configurationfile.

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 systemconsults loggers higher up the hierarchy to determine the effective level of thelogger. The propagate entry is set to 1 to indicate that messages mustpropagate to handlers higher up the logger hierarchy from this logger, or 0 toindicate that messages are not propagated to handlers up the hierarchy. Thequalname entry is the hierarchical channel name of the logger, that is tosay 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 forloggers, and NOTSET is taken to mean 'log everything'.

The formatter entry indicates the key name of the formatter for thishandler. If blank, a default formatter (logging._defaultFormatter) is used.If a name is specified, it must appear in the [formatters] section and havea corresponding section in the configuration file.

The args entry, when eval()uated in the context of the loggingpackage's namespace, is the list of arguments to the constructor for the handlerclass. Refer to the constructors for the relevant handlers, or to the examplesbelow, to see how typical entries are constructed. If not provided, it defaultsto ().

The optional kwargs entry, when eval()uated in the context of thelogging package's namespace, is the keyword argument dict to the constructorfor the handler class. If not provided, it defaults to {}.

[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')
kwargs={'timeout': 10.0}
 
[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')
kwargs={'secure': True}

Sections which specify formatter configuration are typified by the following.

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
class=logging.Formatter

The format entry is the overall format string, and the datefmt entry isthe strftime()-compatible date/time format string. If empty, thepackage substitutes something which is almost equivalent to specifying the dateformat string '%Y-%m-%d %H:%M:%S'. This format also specifies milliseconds,which are appended to the result of using the above format string, with a commaseparator. An example time in this format is 2003-01-23 00:29:50,411.

The class entry is optional. It indicates the name of the formatter's class(as a dotted module and class name.) This option is useful for instantiating aFormatter subclass. Subclasses ofFormatter can present exception tracebacks in an expanded orcondensed format.

注解

Due to the use of eval() as described above, there arepotential security risks which result from using the listen() to sendand receive configurations via sockets. The risks are limited to wheremultiple users with no mutual trust run code on the same machine; see thelisten() documentation for more information.

参见

• 模块 logging

• 日志记录模块的 API 参考。

• 模块 logging.handlers

• 日志记录模块附带的有用处理程序。