Pythonlogging.config日志记录配置

字典架构细节¶

传给 dictConfig() 的字典必须包含以下的键:

• version - 应设为代表架构版本的整数值。 目前唯一有效的值是 1，使用此键可允许架构在继续演化的同时保持向下兼容性。

所有其他键都是可选项，但如存在它们将根据下面的描述来解读。 在下面提到 'configuring dict' 的所有情况下，都将检查它的特殊键 '()' 以确定是否需要自定义实例化。 如果需要，则会使用下面 用户定义对象 所描述的机制来创建一个实例；否则，会使用上下文来确定要实例化的对象。

• formatters - 对应的值将是一个字典，其中每个键是一个格式器 ID 而每个值则是一个描述如何配置相应 Formatter 实例的字典。

  将在配置字典中搜索键 format 和 datefmt (默认值均为 None) 并且这些键会被用于构造 Formatter 实例。

• filters - 对应的值将是一个字典，其中每个键是一个过滤器 ID 而每个值则是一个描述如何配置相应 Filter 实例的字典。

  将在配置字典中搜索键 name (默认值为空字符串) 并且该键会被用于构造 logging.Filter 实例。

• handlers - 对应的值将是一个字典，其中每个键是一个处理程序 ID 而每个值则是一个描述如何配置相应 Handler 实例的字典。

  将在配置字典中搜索下列键:

  • class (强制)。 这是处理程序类的完整限定名称。

  • level (可选)。 处理程序的级别。

  • formatter (可选)。 处理程序所对应格式化器的 ID。

  • filters (可选)。 由处理程序所对应过滤器的 ID 组成的列表。

  所有 其他 键会被作为关键字参数传递给处理程序类的构造器。 例如，给定如下代码段:

  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
  

  ID 为 console 的处理程序会被实例化为 logging.StreamHandler，并使用 sys.stdout 作为下层流。 ID 为 file 的处理程序会被实例化为 logging.handlers.RotatingFileHandler，并附带关键字参数 filename='logconfig.log',maxBytes=1024,backupCount=3。

• loggers - 对应的值将是一个字典，其中每个键是一个日志记录器名称而每个值则是一个描述如何配置相应 Logger 实例的字典。

  将在配置字典中搜索下列键:

  • level (可选)。 日志记录器的级别。

  • propagate (可选)。 日志记录器的传播设置。

  • filters (可选)。 由日志记录器对应过滤器的 ID 组成的列表。

  • handlers (可选)。 由日志记录器对应处理程序的 ID 组成的列表。

  指定的日志记录器将根据指定的级别、传播、过滤器和处理程序来配置。

• root - 这将成为根日志记录器对应的配置。 配置的处理方式将与所有日志记录器一致，除了 propagate 设置将不可用之外。

• incremental - 配置是否要被解读为在现有配置上新增。 该值默认为 False，这意味着指定的配置将以与当前 fileConfig() API 所使用的相同语义来替代现有的配置。

  如果指定的值为 True，配置会按照 增量配置 部分所描述的方式来处理。

• disable_existing_loggers - 是否要禁用任何现有的非根日志记录器。 该设置对应于 fileConfig() 中的同名形参。 如果省略，则此形参默认为 True。 如果 incremental 为 True 则该省会被忽略。

增量配置¶

为增量配置提供完全的灵活性是很困难的。 例如，由于过滤器和格式化器这样的对象是匿名的，一旦完成配置，在增加配置时就不可能引用这些匿名对象。

此外，一旦完成了配置，在运行时任意改变日志记录器、处理程序、过滤器、格式化器的对象图就不是很有必要；日志记录器和处理程序的详细程度只需通过设置级别即可实现控制（对于日志记录器则可设置传播旗标）。 在多线程环境中以安全的方式任意改变对象图也许会导致问题；虽然并非不可能，但这样做的好处不足以抵销其所增加的实现复杂度。

这样，当配置字典的 incremental 键存在且为 True 时，系统将完全忽略任何 formatters 和 filters 条目，并仅会处理 handlers 条目中的 level 设置，以及 loggers 和 root 条目中的 level 和 propagate 设置。

使用配置字典中的值可让配置以封存字典对象的形式通过线路传送给套接字监听器。 这样，长时间运行的应用程序的日志记录的详细程度可随时间改变而无须停止并重新启动应用程序。

对象连接¶

该架构描述了一组日志记录对象 —— 日志记录器、处理程序、格式化器、过滤器 —— 它们在对象图中彼此连接。 因此，该架构需要能表示对象之间的连接。 例如，在配置完成后，一个特定的日志记录器关联到了一个特定的处理程序。 出于讨论的目的，我们可以说该日志记录器代表两者间连接的源头，而处理程序则代表对应的目标。 当然在已配置对象中这是由包含对处理程序的引用的日志记录器来代表的。 在配置字典中，这是通过给每个目标对象一个 ID 来无歧义地标识它，然后在源头对象中使用该 ID 来实现的。

因此，举例来说，考虑以下 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]

（注：这里使用 YAML 是因为它的可读性比表示字典的等价 Python 源码形式更好。）

日志记录器 ID 就是日志记录器的名称，它会在程序中被用来获取对日志记录器的引用，例如 foo.bar.baz。 格式化器和过滤器的 ID 可以是任意字符串值 (例如上面的 brief, precise) 并且它们是瞬态的，因为它们仅对处理配置字典有意义并会被用来确定对象之间的连接，而当配置调用完成时不会在任何地方保留。

上面的代码片段指明名为 foo.bar.baz 的日志记录器应当关联到两个处理程序，它们的 ID 是 h1 和 h2。 h1 的格式化器的 ID 是 brief，而 h2 的格式化器的 ID 是 precise。

用户定义对象¶

此架构支持用户定义对象作为处理程序、过滤器和格式化器。 （日志记录器的不同实例不需要具有不同类型，因此这个配置架构并不支持用户定义日志记录器类。）

要配置的对象是由字典描述的，其中包含它们的配置详情。 在某些地方，日志记录系统将能够从上下文中推断出如何实例化一个对象，但是当要实例化一个用户自定义对象时，系统将不知道要如何做。 为了提供用户自定义对象实例化的完全灵活性，用户需要提供一个‘工厂’函数 —— 即在调用时传入配置字典并返回实例化对象的可调用对象。 这是用一个通过特殊键 '()' 来访问的工厂函数的绝对导入路径来标示的。 下面是一个实际的例子:

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

上面的 YAML 代码片段定义了三个格式化器。 第一个的 ID 为 brief，是带有特殊格式字符串的标准 logging.Formatter 实例。 第二个的 ID 为 default，具有更长的格式同时还显式地定义了时间格式，并将最终实例化一个带有这两个格式字符串的 logging.Formatter。 以 Python 源代码形式显示的 brief 和 default 格式化器具有下列配置子字典:

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

和:

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

并且由于这些字典不包含特殊键 '()'，实例化方式是从上下文中推断出来的：结果会创建标准的 logging.Formatter 实例。 第三个格式器的 ID 为 custom，对应配置子字典为:

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

并且它包含特殊键 '()'，这意味着需要用户自定义实例化方式。 在此情况下，将使用指定的工厂可调用对象。 如果它本身就是一个可调用对象则将被直接使用 —— 否则如果你指定了一个字符串（如这个例子所示）则将使用正常的导入机制来定位实例的可调用对象。 调用该可调用对象将传入配置子字典中 剩余的 条目作为关键字参数。 在上面的例子中，调用将预期返回 ID 为 custom 的格式化器:

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

将 '()' 用作特殊键是因为它不是一个有效的关键字形参名称，这样就不会与调用中使用的关键字参数发生冲突。 '()' 还被用作表明对应值为可调用对象的助记符。

访问外部对象¶

有时一个配置需要引用配置以外的对象，例如 sys.stderr。 如果配置字典是使用 Python 代码构造的，这会很直观，但是当配置是通过文本文件（例如 JSON, YAML）提供的时候就会引发问题。 在一个文本文件中，没有将 sys.stderr 与字符串字面值 'sys.stderr' 区分开来的标准方式。 为了实现这种区分，配置系统会在字符串值中查找规定的特殊前缀并对其做特殊处理。 例如，如果在配置中将字符串字面值 'ext://sys.stderr' 作为一个值来提供，则 ext:// 将被去除而该值的剩余部分将使用正常导入机制来处理。

此类前缀的处理方式类似于协议处理：存在一种通用机制来查找与正则表达式 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ 相匹配的前缀，如果识别出了 prefix，则 suffix 会以与前缀相对应的方式来处理并且处理的结果将替代原字符串值。 如果未识别出前缀，则原字符串将保持不变。

访问内部对象¶

除了外部对象，有时还需要引用配置中的对象。 这将由配置系统针对它所了解的内容隐式地完成。 例如，在日志记录器或处理程序中表示 level 的字符串值 'DEBUG' 将被自动转换为值 logging.DEBUG，而 handlers, filters 和 formatter 条目将接受一个对象 ID 并解析为适当的目标对象。

但是，对于 logging 模块所不了解的用户自定义对象则需要一种更通用的机制。 例如，考虑 logging.handlers.MemoryHandler，它接受一个 target 参数即其所委托的另一个处理程序。 由于系统已经知道存在该类，因而在配置中，给定的 target 只需为相应目标处理程序的的对象 ID 即可，而系统将根据该 ID 解析出处理程序。 但是，如果用户定义了一个具有 alternate 处理程序的 my.package.MyHandler，则配置程序将不知道 alternate 指向的是一个处理程序。 为了应对这种情况，通用解析系统允许用户指定:

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

字符串字面值 'cfg://handlers.file' 将按照与 ext:// 前缀类似的方式被解析为结果字符串，但查找操作是在配置自身而不是在导入命名空间中进行。 该机制允许按点号或按索引来访问，与 str.format 所提供的方式类似。 这样，给定以下代码段:

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.

在该配置中，字符串 'cfg://handlers' 将解析为带有 handlers 键的字典，字符串 'cfg://handlers.email 将解析为 handlers 字典中带有 email 键的字典，依此类推。 字符串 'cfg://handlers.email.toaddrs[1] 将解析为 'dev_team.domain.tld' 而字符串 'cfg://handlers.email.toaddrs[0]' 将解析为值 'support_team@domain.tld'。 subject 值可以使用 'cfg://handlers.email.subject' 或者等价的 'cfg://handlers.email[subject]' 来访问。 后一种形式仅在键包含空格或非字母数字类字符的情况下才需要使用。 如果一个索引仅由十进制数码构成，则将尝试使用相应的整数值来访问，如果有必要则将回退为字符串值。

给定字符串 cfg://handlers.myhandler.mykey.123，这将解析为 config_dict['handlers']['myhandler']['mykey']['123']。 如果字符串被指定为 cfg://handlers.myhandler.mykey[123]，系统将尝试从 config_dict['handlers']['myhandler']['mykey'][123] 中提取值，并在尝试失败时回退为 config_dict['handlers']['myhandler']['mykey']['123']。

导入解析与定制导入器¶

导入解析默认使用内置的 __import__() 函数来执行导入。 你可能想要将其替换为你自己的导入机制：如果是这样的话，你可以替换 DictConfigurator 或其超类 BaseConfigurator 类的 importer 属性。 但是你必须小心谨慎，因为函数是从类中通过描述器方式来访问的。 如果你使用 Python 可调用对象来执行导入，并且你希望在类层级而不是在实例层级上定义它，则你需要用 staticmethod() 来装饰它。 例如:

fromimportlibimportimport_module
fromlogging.configimportBaseConfigurator
BaseConfigurator.importer=staticmethod(import_module)

如果你是在一个配置器的 实例 上设置导入可调用对象则你不需要用 staticmethod() 来装饰。