logging.config — Logging configuration日志记录配置

Source code: Lib/logging/config.py

Important重要的

This page contains only reference information. For tutorials, please see本页仅包含参考信息。有关教程，请参阅

• Basic Tutorial基础教程

• Advanced Tutorial高级教程

• Logging Cookbook日志记录食谱

---

This section describes the API for configuring the logging module.本节介绍用于配置日志模块的API。

Configuration functions配置函数

The following functions configure the logging module. 以下功能配置日志记录模块。They are located in the logging.config module. 它们位于logging.config模块中。Their use is optional — you can configure the logging module using these functions or by making calls to the main API (defined in logging itself) and defining handlers which are declared either in logging or logging.handlers.它们的使用是可选的-您可以使用这些函数配置日志模块，或者通过调用主API（在logging本身中定义）并定义在logging或logging.handlers中声明的处理程序来配置日志记录模块。

logging.config.dictConfig(config)

Takes the logging configuration from a dictionary. 从字典中获取日志记录配置。The contents of this dictionary are described in Configuration dictionary schema below.此字典的内容在下面的配置字典模式中描述。

If an error is encountered during configuration, this function will raise a ValueError, TypeError, AttributeError or ImportError with a suitably descriptive message. 如果在配置过程中遇到错误，此函数将使用适当的描述性消息引发ValueError、TypeError、AttributeError或ImportError。The following is a (possibly incomplete) list of conditions which will raise an error:以下是将引发错误的条件列表（可能不完整）：

• A level which is not a string or which is a string not corresponding to an actual logging level.不是字符串或与实际日志记录级别不对应的字符串的level。

• A propagate value which is not a boolean.不是布尔值的propagate。

• An id which does not have a corresponding destination.没有对应目的地的id。

• A non-existent handler id found during an incremental call.增量调用期间发现不存在的处理程序id。

• An invalid logger name.无效的记录器名称。

• Inability to resolve to an internal or external object.无法解析为内部或外部对象。

Parsing is performed by the DictConfigurator class, whose constructor is passed the dictionary used for configuration, and has a configure() method. 解析由DictConfigurator类执行，其构造函数传递用于配置的字典，并具有configure()方法。The logging.config module has a callable attribute dictConfigClass which is initially set to DictConfigurator. logging.config模块有一个可调用的属性dictConfigClass，该属性最初设置为DictConfigurator。You can replace the value of dictConfigClass with a suitable implementation of your own.您可以用自己的适当实现替换dictConfigClass的值。

dictConfig() calls dictConfigClass passing the specified dictionary, and then calls the configure() method on the returned object to put the configuration into effect:通过指定的字典调用dictConfigClass，然后对返回的对象调用configure()方法以使配置生效：

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

For example, a subclass of DictConfigurator could call DictConfigurator.__init__() in its own __init__(), then set up custom prefixes which would be usable in the subsequent configure() call. 例如，DictConfigurator的子类可以在自己的__init__()中调用DictConfigurator.__init__()，然后设置自定义前缀，这些前缀将在随后的configure()调用中使用。dictConfigClass would be bound to this new subclass, and then dictConfig() could be called exactly as in the default, uncustomized state.将被绑定到这个新的子类，然后dictConfig()可以像在默认的未初始化状态下一样被调用。

New in version 3.2.版本3.2中新增。

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

Reads the logging configuration from a configparser-format file. 从configparser格式文件读取日志记录配置。The format of the file should be as described in Configuration file format. 文件格式应如配置文件格式所述。This function can be called several times from an application, allowing an end user to select from various pre-canned configurations (if the developer provides a mechanism to present the choices and load the chosen configuration).该函数可以从应用程序中多次调用，允许最终用户从各种预封装配置中进行选择（如果开发人员提供了一种机制来呈现选择并加载所选配置）。

Parameters参数

• fname – A filename, or a file-like object, or an instance derived from RawConfigParser. If a RawConfigParser-derived instance is passed, it is used as is. Otherwise, a Configparser is instantiated, and the configuration read by it from the object passed in fname. If that has a readline() method, it is assumed to be a file-like object and read using read_file(); otherwise, it is assumed to be a filename and passed to read().

• defaults – Defaults to be passed to the ConfigParser can be specified in this argument.可以在此参数中指定要传递给ConfigParser的默认值。

• disable_existing_loggers –

  If specified as False, loggers which如果指定为False，则记录程序

  exist when this call is made are left enabled. 发出此呼叫时存在的状态保持启用状态。The default is True because this enables old behaviour in a backward-compatible way. 默认值为True，因为这以向后兼容的方式启用旧行为。This behaviour is to disable any existing non-root loggers unless they or their ancestors are explicitly named in the logging configuration.此行为将禁用任何现有的非根记录器，除非在日志配置中显式命名了它们或它们的祖先。

  param encoding

  The encoding used to open file when fname is filename.fname为文件名时用于打开文件的编码。

Changed in version 3.4:版本3.4中更改： An instance of a subclass of RawConfigParser is now accepted as a value for fname. RawConfigParser子类的实例现在被接受为fname的值。This facilitates:这有助于：

• Use of a configuration file where logging configuration is just part of the overall application configuration.使用配置文件，其中日志记录配置只是整个应用程序配置的一部分。

• Use of a configuration read from a file, and then modified by the using application (e.g. based on command-line parameters or other aspects of the runtime environment) before being passed to fileConfig.使用从文件读取的配置，然后在传递到fileConfig之前由使用应用程序修改（例如，基于命令行参数或运行时环境的其他方面）。

New in version 3.10.版本3.10中新增。The encoding parameter is added.添加encoding参数。

logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)

Starts up a socket server on the specified port, and listens for new configurations. 在指定端口上启动套接字服务器，并侦听新配置。If no port is specified, the module’s default DEFAULT_LOGGING_CONFIG_PORT is used. 如果未指定端口，则使用模块的默认DEFAULT_LOGGING_CONFIG_PORT。Logging configurations will be sent as a file suitable for processing by dictConfig() or fileConfig(). Returns a Thread instance on which you can call start() to start the server, and which you can join() when appropriate. To stop the server, call stopListening().

The verify argument, if specified, should be a callable which should verify whether bytes received across the socket are valid and should be processed. This could be done by encrypting and/or signing what is sent across the socket, such that the verify callable can perform signature verification and/or decryption. The verify callable is called with a single argument - the bytes received across the socket - and should return the bytes to be processed, or None to indicate that the bytes should be 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 and send it to the socket as a sequence of bytes preceded by a four-byte length string packed in binary using struct.pack('>L', n).要将配置发送到套接字，请读入配置文件，并将其作为字节序列发送到套接字。字节序列前面是一个四字节长的字符串，使用struct.pack('>L', n)以二进制形式打包。

Note

Because portions of the configuration are passed through eval(), use of this function may open its users to a security risk. 由于部分配置是通过eval()传递的，因此使用此函数可能会给用户带来安全风险。While the function only binds to a socket on localhost, and so does not accept connections from remote machines, there are scenarios where untrusted code could be run under the account of the process which calls listen(). Specifically, if the process calling listen() runs on a multi-user machine where users cannot trust each other, then a malicious user could arrange to run essentially arbitrary code in a victim user’s process, simply by connecting to the victim’s listen() socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim’s process. This is especially easy to do if the default port is used, but not hard even if a different port is used. To avoid the risk of this happening, use the verify argument to listen() to prevent unrecognised configurations from being applied.

Changed in version 3.4:版本3.4中更改： The verify argument was added.

Note

If you want to send configurations to the listener which don’t disable existing loggers, you will need to use a JSON format for the configuration, which will use dictConfig() for configuration. This method allows you to specify disable_existing_loggers as False 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 from listen().

Security considerations安全考虑

The logging configuration functionality tries to offer convenience, and in part this is done by offering the ability to convert text in configuration files into Python objects used in logging configuration - for example, as described in User-defined objects. 日志记录配置功能试图提供便利，部分是通过提供将配置文件中的文本转换为日志记录配置中使用的Python对象的能力来实现的，例如，如用户定义对象中所述。However, these same mechanisms (importing callables from user-defined modules and calling them with parameters from the configuration) could be used to invoke any code you like, and for this reason you should treat configuration files from untrusted sources with extreme caution and satisfy yourself that nothing bad can happen if you load them, before actually loading them.然而，这些相同的机制（从用户定义的模块中导入可调用函数，并使用配置中的参数调用它们）可以用于调用您喜欢的任何代码，因此，您应该非常谨慎地对待来自不可信源的配置文件，并确保在实际加载它们之前，如果加载它们，不会发生任何错误。

Configuration dictionary schema配置字典架构

Describing a logging configuration requires listing the various objects to create and the connections between them; for example, you may create a handler named ‘console’ and then say that the logger named ‘startup’ will send its messages to the ‘console’ handler. 描述日志记录配置需要列出要创建的各种对象以及它们之间的连接；例如，您可以创建一个名为“控制台”的处理程序，然后说名为“启动”的记录器将向“控制台”处理程序发送消息。These objects aren’t limited to those provided by the logging module because you might write your own formatter or handler class. 这些对象不限于logging模块提供的对象，因为您可以编写自己的格式化程序或处理程序类。The parameters to these classes may also need to include external objects such as sys.stderr. 这些类的参数可能还需要包括外部对象，如sys.stderr。The syntax for describing these objects and connections is defined in Object connections below.下面的对象连接中定义了描述这些对象和连接的语法。

Dictionary Schema Details字典架构详细信息

The dictionary passed to dictConfig() must contain the following keys:传递给dictConfig()的字典必须包含以下键：

• version - to be set to an integer value representing the schema version. 设置为表示模式版本的整数值。The only valid value at present is 1, but having this key allows the schema to evolve while still preserving backwards compatibility.目前唯一有效的值是1，但拥有该键允许模式在保持向后兼容性的同时不断发展。

All other keys are optional, but if present they will be interpreted as described below. 所有其他键都是可选的，但如果存在，它们将按如下所述进行解释。In all cases below where a ‘configuring dict’ is mentioned, it will be checked for the special '()' key to see if a custom instantiation is required. 在下面提到“配置dict”的所有情况下，将检查特殊的'()'键，以查看是否需要自定义实例化。If so, the mechanism described in User-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 each key is a formatter id and each value is a dict describing how to configure the corresponding Formatter instance.相应的值将是一个dict，其中每个键都是格式化程序id，每个值都是一个描述如何配置相应Formatter实例的dict。

  The configuring dict is searched for the following optional keys which correspond to the arguments passed to create a Formatter object:在配置dict中搜索与创建Formatter对象所传递的参数相对应的以下可选键：

  • format

  • datefmt

  • style

  • validate (since version >=3.8)

  An optional class key indicates the name of the formatter’s class (as a dotted module and class name). 可选的class键指示格式化程序类的名称（以虚线模块和类名表示）。The instantiation arguments are as for Formatter, thus this key is most useful for instantiating a customised subclass of Formatter. 实例化参数与Formatter相同，因此该键对于实例化Formatter的自定义子类最有用。For example, the alternative class might present exception tracebacks in an expanded or condensed format. 例如，备选类可能以扩展或压缩格式提供异常回溯。If your formatter requires different or extra configuration keys, you should use User-defined objects.如果格式化程序需要不同或额外的配置键，则应使用用户定义的对象。

• filters - the corresponding value will be a dict in which each key is a filter id and each value is a dict describing how to configure the corresponding Filter instance.相应的值将是一个dict，其中每个键是一个筛选器id，每个值是一个描述如何配置相应筛选器实例的dict。

  The configuring dict is searched for the key name (defaulting to the empty string) and this is used to construct a logging.Filter instance.在配置dict中搜索键name（默认为空字符串），这用于构造logging.Filter实例。

• handlers - the corresponding value will be a dict in which each key is a handler id and each value is a dict describing how to configure the corresponding Handler instance.相应的值将是一个dict，其中每个键是一个处理程序id，每个值是一个描述如何配置相应处理程序实例的dict。

  The configuring dict is searched for the following keys:在配置dict中搜索以下键：

  • class (mandatory). This is the fully qualified name of the handler class.这是处理程序类的完全限定名称。

  • level (optional). The level of the handler.处理程序的级别。

  • formatter (optional). The id of the formatter for this handler.此处理程序的格式化程序的id。

  • filters (optional). A list of ids of the filters for this handler.此处理程序的筛选器的ID列表。

  All other keys are passed through as keyword arguments to the handler’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 a logging.StreamHandler, using sys.stdout as the underlying stream. The handler with id file is instantiated as a logging.handlers.RotatingFileHandler with the keyword arguments filename='logconfig.log', maxBytes=1024, backupCount=3.

• loggers - the corresponding value will be a dict in which each key is a logger name and each value is a dict describing how to configure 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 this logger.

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

  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, except that the propagate setting will not be applicable.配置的处理将与任何记录器相同，但propagate设置不适用。

• incremental - whether the configuration is to be interpreted as incremental to the existing configuration. 是否将配置解释为现有配置的增量。This value defaults to False, which means that the specified configuration replaces the existing configuration with the same semantics as used by the existing fileConfig() API.该值默认为False，这意味着指定的配置将使用与现有fileConfig()API使用的语义相同的语义替换现有配置。

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

• disable_existing_loggers - whether any existing non-root loggers are to be disabled. 是否要禁用任何现有的非根记录器。This setting mirrors the parameter of the same name in fileConfig(). 此设置镜像fileConfig()中同名的参数。If absent, this parameter defaults to True. 如果不存在，则该参数默认为True。This value is ignored if incremental is True.如果增量为真，则忽略此值。

Incremental Configuration增量配置

It is difficult to provide complete flexibility for incremental configuration. 很难为增量配置提供完全的灵活性。For example, because objects such as filters and formatters are anonymous, once a configuration is set up, it is not possible to refer to such anonymous objects when augmenting a configuration.例如，由于筛选器和格式化程序等对象是匿名的，因此一旦设置了配置，就不可能在扩展配置时引用此类匿名对象。

Furthermore, there is not a compelling case for arbitrarily altering the object graph of loggers, handlers, filters, formatters at run-time, once a configuration is set up; the verbosity of loggers and handlers can be controlled just by setting levels (and, in the case of loggers, propagation flags). 此外，一旦设置了配置，就没有必要在运行时任意更改记录器、处理程序、筛选器和格式化程序的对象图；日志记录器和处理程序的详细程度可以通过设置级别（以及在日志记录器的情况下，传播标志）来控制。Changing the object graph arbitrarily in a safe way is problematic in a multi-threaded environment; while not impossible, the benefits are not worth the complexity it adds to the implementation.在多线程环境中，以安全方式任意改变对象图是有问题的；虽然并非不可能，但好处并不值得它增加实现的复杂性。

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

Using a value in the configuration dict lets configurations to be sent over the wire as pickled dicts to a socket listener. 使用配置dict中的值可以将配置作为pickled dict通过线路发送到套接字侦听器。Thus, the logging verbosity of a long-running application can be altered over time with no 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 in an object graph. 该模式描述了一组日志对象-记录器、处理程序、格式化程序和筛选器-它们在对象图中相互连接。Thus, the schema needs to represent connections between the objects. 因此，模式需要表示对象之间的连接。For example, say that, once configured, a particular logger has attached to it a particular handler. 例如，假设配置后，特定的记录器已附加了特定的处理程序。For the purposes of this discussion, we can say that the logger represents the source, and the handler the destination, of a connection between the two. 出于讨论的目的，我们可以说，记录器代表两者之间连接的源，而处理程序代表目标。Of course in the configured objects this is represented by the logger holding a reference to the handler. 当然，在配置的对象中，这由保存对处理程序的引用的记录器表示。In the configuration dict, this is done by giving each destination object an id which identifies it unambiguously, and then using the id in the source object’s configuration to indicate that a connection exists between the source and the destination object with that id.在配置dict中，这是通过给每个目标对象一个标识来完成的，该标识明确地标识了它，然后在源对象的配置中使用该标识来指示源对象和具有该标识的目标对象之间存在连接。

So, for example, consider the following YAML snippet:因此，例如，考虑以下YAML代码段：

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 the equivalent Python source form for the dictionary.)（注意：这里使用YAML是因为它比字典的等效Python源代码形式更可读。）

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

The above snippet indicates that logger named foo.bar.baz should have two handlers attached to it, which are described by the handler ids h1 and h2. The formatter for h1 is that described by id brief, and the formatter for h2 is that described by id precise.

User-defined objects用户定义对象

The schema supports user-defined objects for handlers, filters and formatters. 架构支持处理程序、筛选器和格式化程序的用户定义对象。(Loggers do not need to have different types for different instances, so there is no support in this configuration schema for user-defined logger classes.)（记录器不需要为不同的实例具有不同的类型，因此此配置模式不支持用户定义的记录器类。）

Objects to be configured are described by dictionaries which detail their configuration. 要配置的对象由详细描述其配置的字典描述。In some places, the logging system will be able to infer from the context how an object is to be instantiated, but when a user-defined object is to be instantiated, the system will not know how to do this. 在某些情况下，日志记录系统将能够从上下文中推断对象将如何实例化，但当用户定义的对象将被实例化时，系统将不知道如何执行此操作。In order to provide complete flexibility for user-defined object instantiation, the user needs to provide a ‘factory’ - a callable which is called with a configuration dictionary and which returns the instantiated object. 为了为用户定义的对象实例化提供完全的灵活性，用户需要提供一个“工厂”-一个可调用的，通过配置字典调用并返回实例化的对象。This is signalled by an absolute import path to the factory being made available under the special key '()'. 这通过特殊键'()'提供的工厂的绝对导入路径来表示。Here’s a concrete example:下面是一个具体的例子：

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 id brief, is a standard logging.Formatter instance with the specified format string. The second, with id default, has a longer format and also defines the time format explicitly, and will result in a logging.Formatter initialized with those two format strings. Shown in Python source form, the brief and default formatters have configuration sub-dictionaries:

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

and:

{
  '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. The configuration sub-dictionary for the third formatter, with id custom, is:

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

and this contains the special key '()', which means that user-defined instantiation is wanted. In this case, the specified factory callable will be used. If it is an actual callable it will be used 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 the configuration sub-dictionary as keyword arguments. In the above example, the formatter with id custom will be assumed to be returned 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 a valid keyword parameter name, and so will not clash with the names of the keyword arguments used in the call. The '()' also serves as a mnemonic that the corresponding value is a callable.

Access to external objects访问外部对象

There are times where a configuration needs to refer to objects external to the configuration, for example sys.stderr. If the configuration dict is constructed using Python code, this is straightforward, but a problem arises when the configuration is provided via a text file (e.g. JSON, YAML). In a text file, there is no standard way to distinguish sys.stderr from the literal string 'sys.stderr'. To facilitate this distinction, the configuration system looks for certain special prefixes in string values and treat 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 the value processed using normal import mechanisms.

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

Access to internal objects访问内部对象

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

However, a more generic mechanism is needed for user-defined objects which are not known to the logging module. 然而，对于logging模块不知道的用户定义对象，需要一种更通用的机制。For example, consider logging.handlers.MemoryHandler, which takes a target argument which is another handler to delegate to. Since the system already knows about this class, then in the configuration, the given target just needs to be the object id of the relevant target handler, and the system will resolve to the handler from the id. If, however, a user defines a my.package.MyHandler which has an alternate handler, the configuration system would not know that the alternate referred to a handler. To cater for this, a generic resolution 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 an analogous way to strings with the ext:// prefix, but looking in the configuration itself rather than the import namespace. The mechanism allows access by dot or by index, in a similar way to that 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 to the dict with key handlers, the string 'cfg://handlers.email would resolve to the dict with key email in the handlers dict, and so on. The string 'cfg://handlers.email.toaddrs[1] would resolve 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 accessed using either 'cfg://handlers.email.subject' or, equivalently, 'cfg://handlers.email[subject]'. The latter form only needs to be used if the key contains spaces or non-alphanumeric characters. If an index value consists only of decimal digits, access will be attempted using the corresponding integer value, falling back to the string value if needed.

Given a string cfg://handlers.myhandler.mykey.123, this will resolve 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 from config_dict['handlers']['myhandler']['mykey'][123], and fall back to config_dict['handlers']['myhandler']['mykey']['123'] if that fails.

Import resolution and custom importers导入解析和自定义导入程序

Import resolution, by default, uses the builtin __import__() function to do its importing. You may want to replace this with your own importing mechanism: if so, you can replace the importer attribute of the DictConfigurator or its superclass, the BaseConfigurator class. However, you need to be careful because of the way functions are accessed from classes via descriptors. If you are using a Python callable to do your imports, and you want to define it at class level rather than instance level, you need to wrap it 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 import callable on a configurator instance.

Configuration file format配置文件格式

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 identifies 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].

Note

The fileConfig() API is older than the dictConfig() API and does not provide functionality to cover certain aspects of logging. For example, you cannot configure Filter objects, which provide for filtering of messages beyond simple integer levels, using fileConfig(). If you need to have instances of Filter in your logging configuration, you will need to use dictConfig(). Note that future enhancements to configuration functionality will be added to dictConfig(), so it’s worth considering transitioning to this newer API 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 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. If not provided, it defaults to ().

The optional kwargs entry, when eval()uated in the context of the logging package’s namespace, is the keyword argument dict to the constructor for 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=
style='%'
validate=True
class=logging.Formatter

The arguments for the formatter configuration are the same as the keys in the dictionary schema formatters section.格式化程序配置的参数与字典架构格式化程序部分中的键相同。

Note

Due to the use of eval() as described above, there are potential security risks which result from using the listen() to send and receive configurations via sockets. 由于如上所述使用eval()，因此使用listen()通过套接字发送和接收配置会导致潜在的安全风险。The risks are limited to where multiple users with no mutual trust run code on the same machine; see the listen() documentation for more information.风险仅限于没有相互信任的多个用户在同一台机器上运行代码；有关详细信息，请参阅listen()文档。

See also

Module logging

API reference for the logging module.日志模块的API参考。

Module logging.handlers

Useful handlers included with the logging module.日志模块中包含有用的处理程序。