`logging` ——python的日志记录工具¶

该模块定义了为应用程序和库实现灵活事件日志记录系统的函数和类。

标准库模块提供日志API的主要好处是，所有的python模块都可以参与日志记录，因此您的应用程序日志可以包含您自己的消息，这些消息与来自第三方模块的消息集成在一起。

该模块提供了很多功能和灵活性。如果您不熟悉日志记录，最好的方法是查看教程（请参见右侧的链接）。

模块定义的基本类及其函数如下所示。

记录器公开应用程序代码直接使用的接口。
处理程序将日志记录（由记录器创建）发送到适当的目标。
过滤器提供了一个更细粒度的工具，用于确定要输出哪些日志记录。
格式化程序指定最终输出中日志记录的布局。

记录器对象¶

记录器具有以下属性和方法。注意记录员应该 NEVER 直接实例化，但始终通过模块级功能 logging.getLogger(name) .多次呼叫 getLogger() 具有相同名称的将始终返回对同一记录器对象的引用。

这个 name 可能是一个周期分隔的层次值，例如 foo.bar.baz （尽管它也可能很简单 foo 例如）。层次结构列表中较低的记录器是列表中较高的记录器的子级。例如，给定一个名为 foo ，名为 foo.bar ， foo.bar.baz 和 foo.bam 都是的后代 foo . logger name层次结构类似于python包层次结构，如果使用推荐的结构按模块组织logger，则与之相同。 logging.getLogger(__name__) . 因为在一个模组里， __name__ 是Python包命名空间中模块的名称。

class logging.Logger¶

propagate¶

如果此属性的值为true，则记录到此记录器的事件将传递给更高级别（祖先）记录器的处理程序，以及附加到此记录器的任何处理程序。消息直接传递给祖先记录器的处理程序-不考虑相关祖先记录器的级别和筛选器。

如果计算结果为false，则不会将日志消息传递给祖先记录器的处理程序。

构造函数将此属性设置为 True .

注解

如果将处理程序附加到记录器 and 它的一个或多个祖先，可能会多次发出相同的记录。一般来说，您不需要将处理程序附加到多个记录器上-如果您只是将它附加到记录器层次结构中最高的适当记录器上，那么它将看到所有子代记录器记录的所有事件，前提是它们的传播设置保留为 True . 一个常见的场景是只将处理程序附加到根记录器，并让传播处理其余的。

setLevel(level)¶

将此记录器的阈值设置为 level . 记录不严重于 level 将被忽略；记录具有严重性的消息 level 或更高的级别将由为此记录器提供服务的任何一个或多个处理程序发出，除非已将处理程序的级别设置为比 level .

创建记录器时，级别设置为 NOTSET （当记录器是根记录器时，这将导致所有消息被处理，或者当记录器是非根记录器时，将所有消息委托给父级）。请注意，根记录器是使用级别创建的 WARNING .

术语“对父级的委托”意味着，如果记录器的级别为Notset，则会遍历其祖先记录器链，直到找到具有Notset以外级别的祖先，或者到达根。

如果发现祖先的级别不是notset，那么该祖先的级别将被视为开始祖先搜索的记录器的有效级别，并用于确定如何处理日志事件。

如果到达了根目录，并且它的级别为notset，那么将处理所有消息。否则，根的级别将用作有效级别。

见测井水平以获取级别列表。

在 3.2 版更改: 这个 level 参数现在接受级别（如“info”）的字符串表示形式作为整数常量（如 INFO . 但是请注意，级别内部存储为整数，方法如 getEffectiveLevel() 和 isEnabledFor() 将返回/期望被传递为整数。

isEnabledFor(level)¶: 指示严重性消息水平将由该记录器处理。此方法首先检查由 logging.disable(level) 然后记录者的有效水平由 getEffectiveLevel() .

getEffectiveLevel()¶: 指示此记录器的有效级别。如果值不是 NOTSET 已使用设置 setLevel() ，则返回。否则，层次结构将向根遍历，直到 NOTSET 找到，并返回该值。返回的值是一个整数，通常是 logging.DEBUG ， logging.INFO 等。

getChild(suffix)¶: 返回一个记录器，该记录器是此记录器的后代，由后缀确定。因此， logging.getLogger('abc').getChild('def.ghi') 将返回与返回相同的记录器 logging.getLogger('abc.def.ghi') . 这是一种方便的方法，当使用例如 __name__ 而不是文字字符串。

3.2 新版功能.

debug(msg, *args, **kwargs)¶

用级别记录消息 DEBUG 在这个记录器上。这个 msg 是消息格式字符串，并且 args 是否将参数合并到 msg 使用字符串格式化运算符。（注意，这意味着您可以将格式字符串中的关键字与单个字典参数一起使用。）不执行%格式操作 msg 当没有的时候 args 提供。

中有四个关键字参数 关键字参数 检查内容： exc_info ， stack_info ， 堆积层 和 额外的 .

如果 exc_info 不计算为假，它将导致异常信息添加到日志消息中。如果异常元组（格式由返回 sys.exc_info() ）或者提供了异常实例，则使用该实例；否则， sys.exc_info() 调用以获取异常信息。

第二个可选关键字参数是 stack_info ，默认为 False . 如果为true，则将向日志消息添加堆栈信息，包括实际的日志调用。请注意，这与通过指定 exc_info ：前者是从堆栈底部到当前线程中的日志记录调用的堆栈帧，而后者是有关在搜索异常处理程序时发生异常后已解除绑定的堆栈帧的信息。

您可以指定 stack_info 独立于 exc_info 例如，在代码中显示如何到达某个点，即使没有引发异常。堆栈帧按照标题行打印，标题行表示：

Stack (most recent call last):

这模仿了 Traceback (most recent call last): 在显示异常帧时使用。

第三个可选关键字参数是 堆积层 ，默认为 1 . 如果大于1，则在计算在 LogRecord 为日志记录事件创建。这可用于记录助手，以便记录的函数名、文件名和行号不是助手函数/方法的信息，而是助手函数/方法的调用方。此参数的名称反映了 warnings 模块。

第四个关键字参数是 额外的 可用于传递用于填充 __dict__ 的 LogRecord 为具有用户定义属性的日志记录事件创建。然后可以根据需要使用这些自定义属性。例如，它们可以合并到日志消息中。例如：：

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

打印一些像

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

字典中的键传入 额外的 不应与日志记录系统使用的键冲突。（见 Formatter 有关日志记录系统使用哪些键的详细信息，请参阅文档。）

如果您选择在记录的消息中使用这些属性，则需要格外小心。例如，在上面的示例中， Formatter 已使用格式字符串设置，该字符串应为的属性字典中的“clientip”和“user” LogRecord . 如果缺少这些，则不会记录消息，因为将发生字符串格式异常。所以在这种情况下，你总是需要通过 额外的 带这些键的字典。

虽然这可能很烦人，但此功能旨在在特殊情况下使用，例如多线程服务器，其中相同的代码在许多上下文中执行，并且出现的有趣条件依赖于此上下文（如上面的示例中的远程客户端IP地址和已验证的用户名）。在这种情况下，很可能 Formatter S将与特定的 Handler S

在 3.2 版更改: 这个 stack_info 已添加参数。

在 3.5 版更改: 这个 exc_info 参数现在可以接受异常实例。

在 3.8 版更改: 这个 堆积层 已添加参数。

info(msg, *args, **kwargs)¶: 用级别记录消息 INFO 在这个记录器上。这些参数被解释为 debug() .

warning(msg, *args, **kwargs)¶: 用级别记录消息 WARNING 在这个记录器上。这些参数被解释为 debug() .

注解

有一种过时的方法 warn 其功能与 warning . AS warn 已弃用，请不要使用-使用 warning 相反。

error(msg, *args, **kwargs)¶: 用级别记录消息 ERROR 在这个记录器上。这些参数被解释为 debug() .

critical(msg, *args, **kwargs)¶: 用级别记录消息 CRITICAL 在这个记录器上。这些参数被解释为 debug() .

log(level, msg, *args, **kwargs)¶: 用整数级别记录消息水平在这个记录器上。其他参数解释为 debug() .

exception(msg, *args, **kwargs)¶: 用级别记录消息 ERROR 在这个记录器上。这些参数被解释为 debug() . 异常信息将添加到日志消息中。只能从异常处理程序调用此方法。

addFilter(filter)¶: 添加指定的筛选器 滤波器 给这个记录器。

removeFilter(filter)¶: 删除指定的筛选器 滤波器 从这个记录器。

filter(record)¶: 将此记录器的筛选器应用于记录并返回 True 如果要处理记录。依次查询过滤器，直到其中一个返回假值。如果它们都不返回假值，则将处理记录（传递给处理程序）。如果返回一个假值，则不会对记录进行进一步处理。

addHandler(hdlr)¶: 添加指定的处理程序 hdlr 给这个记录器。

removeHandler(hdlr)¶: 删除指定的处理程序 hdlr 从这个记录器。

findCaller(stack_info=False, stacklevel=1)¶

查找调用者的源文件名和行号。以4元素元组的形式返回文件名、行号、函数名和堆栈信息。堆栈信息返回为 None 除非 stack_info 是 True .

这个 堆积层 参数是从调用 debug() 和其他API。如果大于1，则在确定要返回的值之前，多余的值用于跳过堆栈帧。当从帮助器/封装器代码调用日志记录API时，这通常很有用，这样事件日志中的信息就不会指向帮助器/封装器代码，而是指向调用它的代码。

handle(record)¶: 通过将记录传递给与此记录器及其祖先关联的所有处理程序来处理记录（直到错误值为传播找到）。此方法用于从套接字接收的未选取记录以及本地创建的记录。日志级别筛选应用于 filter() .

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)¶: 这是一个工厂方法，可以在子类中重写以创建专用的 LogRecord 实例。

hasHandlers()¶: 检查此记录器是否配置了任何处理程序。这是通过在记录器层次结构中查找此记录器及其父级中的处理程序来完成的。返回 True 如果找到处理程序，则返回 False . 只要找到“propagate”属性设置为false的记录器，该方法就会停止搜索层次结构-这将是最后一个检查是否存在处理程序的记录器。

3.2 新版功能.

在 3.7 版更改: 伐木工人现在可以被腌制和剥皮了。

测井水平¶

下表给出了日志记录级别的数值。如果您希望定义自己的级别，并且需要它们具有与预定义级别相关的特定值，那么它们主要是有意义的。如果定义的级别具有相同的数值，它将覆盖预定义的值；预定义的名称将丢失。

水平	数值
`CRITICAL`	50
`ERROR`	40
`WARNING`	30
`INFO`	20
`DEBUG`	10
`NOTSET`	0

处理对象¶

处理程序具有以下属性和方法。注意 Handler 从不直接实例化；此类充当更有用的子类的基础。然而， __init__() 子类中的方法需要调用 Handler.__init__() .

class logging.Handler¶

__init__(level=NOTSET)¶: 初始化 Handler 实例通过设置其级别，将过滤器列表设置为空列表并创建锁（使用 createLock() ）用于串行化对I/O机制的访问。

createLock()¶: 初始化线程锁，该线程锁可用于序列化对可能不是线程安全的底层I/O功能的访问。

acquire()¶: 获取用创建的线程锁 createLock() .

release()¶: 释放获取的线程锁 acquire() .

setLevel(level)¶

将此处理程序的阈值设置为 level . 记录不严重于 level 将被忽略。创建处理程序时，级别设置为 NOTSET （导致所有消息被处理）。

见测井水平以获取级别列表。

在 3.2 版更改: 这个 level 参数现在接受级别（如“info”）的字符串表示形式作为整数常量（如 INFO .

setFormatter(fmt)¶: 设置 Formatter 对于此处理程序 fmt .

addFilter(filter)¶: 添加指定的筛选器 滤波器 到这个处理程序。

removeFilter(filter)¶: 删除指定的筛选器 滤波器 来自此处理程序。

filter(record)¶: 将此处理程序的筛选器应用于记录并返回 True 如果要处理记录。依次查询过滤器，直到其中一个返回假值。如果它们都不返回假值，则会发出记录。如果返回一个假值，处理程序将不会发出记录。

flush()¶: 确保所有日志记录输出都已刷新。这个版本不做任何事情，并且打算由子类实现。

close()¶: 整理处理程序使用的所有资源。此版本不输出，但从内部处理程序列表中删除处理程序，当 shutdown() 被称为。子类应确保从重写的 close() 方法。

handle(record)¶: 根据可能已添加到处理程序的筛选器，有条件地发出指定的日志记录。使用I/O线程锁的采集/释放来封装记录的实际发射。

handleError(record)¶: 当在 emit() 调用。如果模块级属性 raiseExceptions 是 False ，将自动忽略异常。这是日志系统最需要的——大多数用户不会关心日志系统中的错误，他们对应用程序错误更感兴趣。但是，如果愿意，可以用自定义处理程序替换它。指定的记录是发生异常时正在处理的记录。（默认值为 raiseExceptions 是 True 因为这在开发过程中更有用）。

format(record)¶: 对记录进行格式化-如果设置了格式化程序，请使用它。否则，请使用模块的默认格式化程序。

emit(record)¶: 尽一切可能记录指定的日志记录。此版本旨在通过子类实现，因此引发 NotImplementedError .

有关作为标准包含的处理程序列表，请参阅 logging.handlers .

格式化程序对象¶

Formatter 对象具有以下属性和方法。他们负责转换 LogRecord （通常）可以由人或外部系统解释的字符串。底座 Formatter 允许指定格式字符串。如果未提供，则默认值为 '%(message)s' 使用，它只在日志记录调用中包含消息。要在格式化的输出中包含其他信息项（如时间戳），请继续读取。

格式化程序可以使用格式字符串初始化，该字符串利用 LogRecord 属性-例如上面提到的默认值，利用用户的消息和参数预先格式化为 LogRecord 的消息属性。此格式字符串包含标准的python%—样式映射键。见节 printf -样式字符串格式有关字符串格式的详细信息。

中的有用映射键 LogRecord 在日志记录属性 .

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)¶

返回的新实例 Formatter 类。实例初始化时使用消息整体的格式字符串，以及消息日期/时间部分的格式字符串。如果没有 fmt 已指定， '%(message)s' 使用。如果没有 日期fmt 如果指定，则使用的格式在 formatTime() 文档。

这个风格参数可以是“%”、“”或“$”之一，并确定格式字符串将如何与其数据合并：使用“%”格式之一， str.format() 或 string.Template . 这只适用于格式字符串 fmt （例如） '%(message)s' 或 {{message}} )，而不是传递给 Logger.debug 等；见在整个应用程序中使用特定的格式样式有关为日志消息使用和$-格式的详细信息。

这个 默认值 参数可以是具有默认值的字典，以便在自定义字段中使用。例如： logging.Formatter('%(ip)s %(message)s', defaults={{"ip": None}})

在 3.2 版更改: 这个风格已添加参数。

在 3.8 版更改: 这个 validate 已添加参数。不正确或不匹配的样式和fmt将引发 ValueError . 例如： logging.Formatter('%(asctime)s - %(message)s', style='{{') .

在 3.10 版更改: 这个 默认值 已添加参数。

format(record)¶

记录的属性字典用作字符串格式化操作的操作数。返回结果字符串。在格式化字典之前，执行了两个准备步骤。这个消息记录的属性是使用 msg % args . 如果格式化字符串包含 '(asctime)' ， formatTime() 调用以格式化事件时间。如果有异常信息，则使用 formatException() 并附加到消息中。请注意，格式化的异常信息缓存在属性中 exc_text . 这很有用，因为异常信息可以被酸洗并通过线路发送，但是如果您有多个异常信息，则应小心。 Formatter 自定义异常信息格式的子类。在这种情况下，必须清除缓存值（通过设置 exc_text 属性到 None )格式化程序完成格式化后，下一个处理事件的格式化程序不使用缓存值，而是重新计算它。

如果堆栈信息可用，它将附加在异常信息之后，使用 formatStack() 必要时进行转换。

formatTime(record, datefmt=None)¶

此方法应从 format() 由想要利用格式化时间的格式化程序执行。可以在格式化程序中重写此方法以提供任何特定的需求，但基本行为如下：如果 日期fmt （字符串）被指定，它与 time.strftime() 格式化记录的创建时间。否则，将使用格式“%y-%m-%d%h:%m:%s，UUU”，其中UUU部分是毫秒值，其他字母是根据 time.strftime() 文档。这种格式的示例时间是 2003-01-23 00:29:50,411 . 返回结果字符串。

此函数使用用户可配置的函数将创建时间转换为元组。默认情况下， time.localtime() 用于；若要为特定格式化程序实例更改此设置，请设置 converter 与具有相同签名的函数的属性 time.localtime() 或 time.gmtime() . 要为所有格式化程序更改它，例如，如果希望以GMT显示所有日志记录时间，请设置 converter 属性 Formatter 类。

在 3.3 版更改: 以前，默认格式是硬编码的，如本例所示： 2010-09-06 22:38:15,292 其中逗号前面的部分由strptime格式字符串处理 ('%Y-%m-%d %H:%M:%S' ，逗号后的部分是毫秒值。因为strptime在毫秒内没有格式占位符，所以毫秒值将使用另一个格式字符串追加， '%s,%03d' ---这两个格式字符串都已硬编码到这个方法中。通过更改，这些字符串被定义为类级属性，可以在需要时在实例级覆盖这些属性。属性的名称是 default_time_format （对于strptime格式字符串）和 default_msec_format （用于附加毫秒值）。

在 3.9 版更改: 这个 default_msec_format 可以是 None .

formatException(exc_info)¶: 格式化指定的异常信息（由返回的标准异常元组 sys.exc_info() ）作为字符串。此默认实现只使用 traceback.print_exception() . 返回结果字符串。

formatStack(stack_info)¶: 格式化指定的堆栈信息（由返回的字符串 traceback.print_stack() ，但删除最后一行）作为字符串。这个默认实现只返回输入值。

过滤对象¶

Filters 可以用 Handlers 和 Loggers 比级别提供的过滤更复杂。基本筛选器类只允许低于记录器层次结构中某个点的事件。例如，使用“a.b”初始化的筛选器将允许日志记录程序“a.b”、“a.b.c”、“a.b.c.d”、“a.b.d”等记录事件，但不允许使用“a.b b”、“b.a.b”等记录事件。如果使用空字符串初始化，则传递所有事件。

class logging.Filter(name='')¶

返回的实例 Filter 类。如果 name 如果指定，它将命名一个记录器，该记录器及其子级将通过筛选器允许其事件。如果 name 是空字符串，允许每个事件。

filter(record)¶: 是否要记录指定的记录？否返回零，是返回非零。如果认为合适，可以通过这种方法对记录进行适当的修改。

请注意，在处理程序发出事件之前，将查询附加到处理程序的筛选器，而在记录事件时（使用 debug() ， info() 等），然后将事件发送到处理程序。这意味着，子代记录器生成的事件不会被记录器的筛选器设置筛选，除非该筛选器也应用于这些子代记录器。

实际上您不需要子类 Filter ：您可以传递具有 filter 方法具有相同的语义。

在 3.2 版更改: 你不需要创建专门的 Filter 类，或使用其他类 filter 方法：可以使用函数（或其他可调用函数）作为筛选器。筛选逻辑将检查筛选对象是否具有 filter 属性：如果是，则假定为 Filter 及其 filter() 方法被调用。否则，假定它是可调用的，并以记录作为单个参数进行调用。返回值应与返回值一致 filter() .

尽管过滤器主要用于根据比级别更复杂的标准筛选记录，但它们可以看到由它们所附加的处理程序或记录器处理的每个记录：如果您想计算特定的记录程序或处理程序处理了多少记录，或者添加、更改或删除记录，这可能很有用。在中提供属性 LogRecord 正在处理。显然，更改日志记录需要小心，但它确实允许向日志中注入上下文信息（请参见使用过滤器传递上下文信息）

日志记录对象¶

LogRecord 实例由 Logger 每次记录某些内容时，都可以通过 makeLogRecord() （例如，来自通过线路接收的酸洗事件）。

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)¶

包含与正在记录的事件相关的所有信息。

传递主要信息 msg 和 args ，组合使用 msg % args 创建 message 记录的字段。

参数

name -- 用于记录此日志记录表示的事件的日志记录程序的名称。请注意，这个名称将始终具有这个值，即使它可能是由附加到不同（祖先）记录器的处理程序发出的。
level -- 日志记录事件的数字级别（调试、信息等之一）请注意，它被转换为 two 日志记录的属性： levelno 对于数值和 levelname 对应的级别名称。
pathname -- 进行日志记录调用的源文件的完整路径名。
lineno -- 进行日志记录调用的源文件中的行号。
msg -- 事件描述消息，可能是带有变量数据占位符的格式字符串。
args -- 要合并到的变量数据 msg 获取事件描述的参数。
exc_info -- 具有当前异常信息的异常元组，或者 None 如果没有可用的异常信息。
func -- 调用日志记录调用的函数或方法的名称。
sinfo -- 一个文本字符串，表示从当前线程堆栈的基到日志记录调用的堆栈信息。

getMessage()¶: 返回此消息 LogRecord 将用户提供的任何参数与消息合并后的实例。如果用户为日志调用提供的消息参数不是字符串， str() 调用它以将其转换为字符串。这允许使用用户定义的类作为消息， __str__ 方法可以返回要使用的实际格式字符串。

在 3.2 版更改: 创建一个 LogRecord 已通过提供用于创建记录的工厂进行了更高的配置。工厂可以使用 getLogRecordFactory() 和 setLogRecordFactory() （工厂签字见此页）。

此功能可用于将您自己的值注入 LogRecord 在创建时。您可以使用以下模式：

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

使用这种模式，可以将多个工厂链接起来，只要它们不覆盖彼此的属性或无意中覆盖上面列出的标准属性，就不会有任何意外。

日志记录属性¶

日志记录有许多属性，其中大部分是从构造函数的参数派生的。（请注意，名称并不总是精确对应于logrecord构造函数参数和logrecord属性。）这些属性可用于将记录中的数据合并到格式字符串中。下表列出了属性名（按字母顺序排列）、它们的含义以及百分比样式格式字符串中相应的占位符。

如果使用-格式 (str.format() ），您可以使用 {{attrname}} 作为格式字符串中的占位符。如果您使用的是$-格式 (string.Template ）使用表单 ${{attrname}} . 当然，在这两种情况下，都要更换 attrname 使用要使用的实际属性名。

在-格式化的情况下，您可以通过将格式标志放在属性名之后（用冒号分隔）来指定格式标志。例如：的占位符 {{msecs:03d}} 将格式化毫秒值 4 作为 004 . 参考 str.format() 有关您可用选项的完整详细信息的文档。

属性名	格式	描述
阿尔茨海默病	你不需要自己格式化。	参数的元组合并到 `msg` 生产 `message` 或其值用于合并的dict（当只有一个参数，并且它是字典时）。
上升时间	`%(asctime)s`	人类可读时间 `LogRecord` 创建。默认情况下，格式为“2003-07-08 16:49:45896”（逗号后的数字是时间的毫秒部分）。
创建	`%(created)f`	时间当 `LogRecord` 已创建（由返回 `time.time()` ）
exc_info	你不需要自己格式化。	异常元组 `sys.exc_info` ）或者，如果没有发生异常， `None` .
文件名	`%(filename)s`	的文件名部分 `pathname` .
函数名	`%(funcName)s`	包含日志记录调用的函数的名称。
平名	`%(levelname)s`	消息的文本日志记录级别 (`'DEBUG'` ， `'INFO'` ， `'WARNING'` ， `'ERROR'` ， `'CRITICAL'` ）
水平不	`%(levelno)s`	消息的数字日志记录级别 (`DEBUG` ， `INFO` ， `WARNING` ， `ERROR` ， `CRITICAL` ）
林诺	`%(lineno)d`	发出日志记录调用的源行号（如果可用）。
消息	`%(message)s`	记录的消息，计算为 `msg % args` . 这是设定时间 `Formatter.format()` 被调用。
模块	`%(module)s`	模块（名称部分 `filename` ）
毫秒	`%(msecs)d`	当 `LogRecord` 创建。
味精	你不需要自己格式化。	原始日志记录调用中传递的格式字符串。合并 `args` 生产 `message` 或任意对象（请参见将任意对象用作消息）
名称	`%(name)s`	用于记录调用的记录器的名称。
路径名	`%(pathname)s`	发出日志记录调用的源文件的完整路径名（如果可用）。
过程	`%(process)d`	进程ID（如果可用）。
进程名	`%(processName)s`	进程名称（如果可用）。
相对应的	`%(relativeCreated)d`	创建日志记录的时间（以毫秒计），相对于加载日志模块的时间。
stack_info	你不需要自己格式化。	当前线程中堆栈底部的堆栈帧信息（如果可用），直至并包括导致创建此记录的日志调用的堆栈帧。
线	`%(thread)d`	线程ID（如果可用）。
线程名	`%(threadName)s`	线程名称（如果可用）。

在 3.1 版更改: 进程名 加入。

loggeradapter对象¶

LoggerAdapter 实例用于方便地将上下文信息传递到日志调用中。有关用法示例，请参见 adding contextual information to your logging output .

class logging.LoggerAdapter(logger, extra)¶

返回的实例 LoggerAdapter 用底层初始化 Logger 实例和类似dict的对象。

process(msg, kwargs)¶: 修改传递给日志记录调用的消息和/或关键字参数，以便插入上下文信息。此实现将传递的对象作为 额外的 到构造函数并将其添加到 关键字参数 使用“Extra”键。返回值为（ msg ， 关键字参数 ）传递了参数（可能已修改）版本的元组。

除上述内容外， LoggerAdapter 支持以下方法 Logger ： debug() ， info() ， warning() ， error() ， exception() ， critical() ， log() ， isEnabledFor() ， getEffectiveLevel() ， setLevel() 和 hasHandlers() .这些方法与中的对应方法具有相同的签名。 Logger ，因此您可以互换使用这两种类型的实例。

在 3.2 版更改: 这个 isEnabledFor() ， getEffectiveLevel() ， setLevel() 和 hasHandlers() 方法已添加到 LoggerAdapter . 这些方法委托给底层记录器。

线程安全性¶

日志模块旨在保证线程安全，而不需要客户机执行任何特殊工作。它通过使用线程锁来实现这一点；有一个锁可以序列化对模块共享数据的访问，并且每个处理程序还创建一个锁来序列化对其底层I/O的访问。

如果要使用 signal 模块，您可能无法在此类处理程序中使用日志记录。这是因为在 threading 模块并不总是可重入的，因此不能从此类信号处理程序调用。

模块级功能¶

除了上面描述的类之外，还有许多模块级函数。

logging.getLogger(name=None)¶

返回具有指定名称的记录器，如果名称为 None ，返回层次结构的根记录器。如果指定，名称通常是点分隔的层次名称，如 'a' ， 'a.b' 或 'a.b.c.d' . 这些名称的选择完全取决于使用日志记录的开发人员。

使用给定名称对此函数的所有调用都返回相同的记录器实例。这意味着记录器实例不需要在应用程序的不同部分之间传递。

logging.getLoggerClass()¶

返回任一标准 Logger 类，或传递给的最后一个类 setLoggerClass() . 可以从新的类定义中调用此函数，以确保安装自定义的 Logger 类不会撤消已由其他代码应用的自定义项。例如：：

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()¶

返回用于创建 LogRecord .

3.2 新版功能: 此功能与 setLogRecordFactory() ，以允许开发人员更多地控制 LogRecord 构造了表示日志事件的。

见 setLogRecordFactory() 有关如何调用工厂的详细信息。

logging.debug(msg, *args, **kwargs)¶

用级别记录消息 DEBUG 在根记录器上。这个 msg 是消息格式字符串，并且 args 是否将参数合并到 msg 使用字符串格式运算符。（请注意，这意味着您可以在格式字符串中使用关键字，以及单个字典参数。）

中有三个关键字参数 关键字参数 检查内容： exc_info 如果不计算为假，则会导致异常信息添加到日志消息中。如果异常元组（格式由返回 sys.exc_info() ）或者提供了异常实例，则使用该实例；否则， sys.exc_info() 调用以获取异常信息。

第二个可选关键字参数是 stack_info ，默认为 False . 如果为true，则将向日志消息添加堆栈信息，包括实际的日志调用。请注意，这与通过指定 exc_info ：前者是从堆栈底部到当前线程中的日志记录调用的堆栈帧，而后者是有关在搜索异常处理程序时发生异常后已解除绑定的堆栈帧的信息。

您可以指定 stack_info 独立于 exc_info 例如，在代码中显示如何到达某个点，即使没有引发异常。堆栈帧按照标题行打印，标题行表示：

Stack (most recent call last):

这模仿了 Traceback (most recent call last): 在显示异常帧时使用。

第三个可选关键字参数是 额外的 可用于传递用于填充 __dict__ 为具有用户定义属性的日志事件创建的日志记录。然后可以根据需要使用这些自定义属性。例如，它们可以合并到日志消息中。例如：：

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning('Protocol problem: %s', 'connection reset', extra=d)

打印内容如下：

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

字典中的键传入 额外的 不应与日志记录系统使用的键冲突。（见 Formatter 有关日志记录系统使用哪些键的详细信息，请参阅文档。）

如果您选择在记录的消息中使用这些属性，则需要格外小心。例如，在上面的示例中， Formatter 已使用格式字符串设置，该字符串应在日志记录的属性字典中包含“clientip”和“user”。如果缺少这些，则不会记录消息，因为将发生字符串格式异常。所以在这种情况下，你总是需要通过 额外的 带这些键的字典。

虽然这可能很烦人，但此功能旨在在特殊情况下使用，例如多线程服务器，其中相同的代码在许多上下文中执行，并且出现的有趣条件依赖于此上下文（如上面的示例中的远程客户端IP地址和已验证的用户名）。在这种情况下，很可能 Formatter S将与特定的 Handler S

在 3.2 版更改: 这个 stack_info 已添加参数。

logging.info(msg, *args, **kwargs)¶: 用级别记录消息 INFO 在根记录器上。这些参数被解释为 debug() .

logging.warning(msg, *args, **kwargs)¶: 用级别记录消息 WARNING 在根记录器上。这些参数被解释为 debug() .

注解

有一个过时的函数 warn 其功能与 warning . AS warn 已弃用，请不要使用-使用 warning 相反。

logging.error(msg, *args, **kwargs)¶: 用级别记录消息 ERROR 在根记录器上。这些参数被解释为 debug() .

logging.critical(msg, *args, **kwargs)¶: 用级别记录消息 CRITICAL 在根记录器上。这些参数被解释为 debug() .

logging.exception(msg, *args, **kwargs)¶: 用级别记录消息 ERROR 在根记录器上。这些参数被解释为 debug() . 异常信息将添加到日志消息中。只能从异常处理程序调用此函数。

logging.log(level, msg, *args, **kwargs)¶: 用级别记录消息 level 在根记录器上。其他参数解释为 debug() .

注解

上述模块级的便利功能委托给根记录器，调用 basicConfig() 以确保至少有一个处理程序可用。因此，他们应该 not 在线程中、在2.7.1和3.2之前的Python版本中使用，除非至少有一个处理程序已添加到根记录器中。 before 线程已启动。在早期版本的python中，由于 basicConfig() ，这可能（在极少数情况下）导致处理程序被多次添加到根记录器中，从而导致同一事件出现多条消息。

logging.disable(level=CRITICAL)¶

提供覆盖级别水平对于所有优先于记录器自身级别的记录器。当需要临时限制整个应用程序的日志记录输出时，此函数可能很有用。它的作用是禁用所有严重性的日志调用水平下面，这样，如果您使用info值调用它，那么所有的info和debug事件都将被丢弃，而那些严重性警告及以上的事件将根据记录器的有效级别进行处理。如果 logging.disable(logging.NOTSET) 被调用时，它会有效地删除这个覆盖级别，以便日志输出再次取决于各个记录器的有效级别。

请注意，如果您定义了高于 CRITICAL （不建议这样做），您将无法依赖水平参数，但必须显式提供适当的值。

在 3.7 版更改: 这个级别参数默认为Level CRITICAL 。看见 bpo-28524 有关此更改的详细信息，请参阅。

logging.addLevelName(level, levelName)¶: 员工级别水平带文字平名在内部字典中，用于将数字级别映射到文本表示形式，例如当 Formatter 格式化消息。此函数还可用于定义您自己的级别。唯一的限制是使用的所有级别都必须使用此函数注册，级别应该是正整数，并且应该按严重性的增加顺序增加。

注解

如果您想定义自己的级别，请参见自定义级别 .

logging.getLevelName(level)¶: 返回日志级别的文本表示形式水平 . 如果级别是预定义的级别之一 CRITICAL ， ERROR ， WARNING ， INFO 或 DEBUG 然后得到相应的字符串。如果将级别与名称关联，请使用 addLevelName() 然后是与您关联的名称水平被退回。如果传入与某个定义级别对应的数值，则返回相应的字符串表示形式。否则，将返回字符串“级别%s%”级别。

注解

级别是内部整数（因为它们需要在日志逻辑中进行比较）。此函数用于在整数级别和格式化日志输出中显示的级别名称之间通过 %(levelname)s 格式说明符（请参见日志记录属性）

在 3.4 版更改: 在3.4之前的Python版本中，该函数还可以传递一个文本级别，并返回该级别的相应数值。这种未记录的行为被认为是错误的，在Python3.4中被删除，但由于保持向后兼容性，在3.4.2中恢复了。

logging.makeLogRecord(attrdict)¶: 创建并返回新的 LogRecord 属性由定义的实例 吸引力 . 此函数可用于 LogRecord 属性字典，通过套接字发送，并将其重新构造为 LogRecord 接收端实例。

logging.basicConfig(**kwargs)¶

通过创建一个 StreamHandler 默认情况下 Formatter 并将其添加到根记录器中。功能 debug() ， info() ， warning() ， error() 和 critical() 将调用 basicConfig() 如果没有为根记录器定义处理程序，则自动执行。

如果根记录器已经配置了处理程序，则此函数不执行任何操作，除非关键字参数 force 设置为 True .

注解

在启动其他线程之前，应该从主线程调用此函数。在2.7.1和3.2之前的Python版本中，如果从多个线程调用此函数，则有可能（在极少数情况下）将一个处理程序多次添加到根日志记录器中，从而导致意外的结果，如日志中的消息被复制。

支持以下关键字参数。

格式	描述
filename	指定 `FileHandler` 使用指定的文件名而不是 `StreamHandler` .
文件格式	如果 filename 已指定，请在此文件中打开 mode .默认为 `'a'` .
格式	使用处理程序的指定格式字符串。默认为属性 `levelname` ， `name` 和 `message` 用冒号隔开的。
日期fmt	使用指定的日期/时间格式，由接受 `time.strftime()` .
风格	如果格式如果已指定，请将此样式用于格式字符串。什么之中的一个 `'%'` ， `'{{'` 或 `'$'` 对于 printf-style ， `str.format()` 或 `string.Template` 分别。默认为 `'%'` .
level	将根记录器级别设置为指定的 level .
流动	使用指定的流初始化 `StreamHandler` . 请注意，此参数与不兼容文件名 -如果两者都存在，a `ValueError` 提高了。
处理程序	如果指定，这应该是已创建的要添加到根记录器的处理程序的ITable。任何尚未设置格式化程序的处理程序都将被分配在此函数中创建的默认格式化程序。请注意，此参数与 filename 或流动 -如果两者都存在，a `ValueError` 提高了。
force	如果将此关键字参数指定为true，则在执行由其他参数指定的配置之前，将删除并关闭附加到根记录器的任何现有处理程序。
编码	如果同时指定此关键字参数文件名，当 `FileHandler` 在打开输出文件时使用。
错误	如果同时指定此关键字参数文件名，当 `FileHandler` 在打开输出文件时使用。如果未指定，则使用值“反斜杠替换”。注意如果 `None` ，则它将作为 `open()` ，这意味着它将被视为传递“错误”。

在 3.2 版更改: 这个风格已添加参数。

在 3.3 版更改: 这个 处理程序 已添加参数。添加了额外的检查以捕获指定了不兼容参数的情况（例如 处理程序 与流动或 filename 或流动与 filename ）

在 3.8 版更改: 这个 force 已添加参数。

在 3.9 版更改: 这个编码和错误已添加参数。

logging.shutdown()¶

通知日志记录系统通过刷新和关闭所有处理程序来执行有序关闭。这应该在应用程序退出时调用，并且在调用之后不应该进一步使用日志记录系统。

当日志模块导入时，它将此函数注册为退出处理程序（请参见 atexit ，所以通常不需要手动操作。

logging.setLoggerClass(klass)¶: 告诉日志记录系统使用类 克拉斯 在实例化记录器时。类应该定义 __init__() 这样就只需要一个名称参数，并且 __init__() 应该打电话 Logger.__init__() . 此函数通常在需要使用自定义记录器行为的应用程序实例化任何记录器之前调用。在这个调用之后，和其他任何时候一样，不要使用子类直接实例化记录器：继续使用 logging.getLogger() 获取日志的API。

logging.setLogRecordFactory(factory)¶

设置用于创建 LogRecord .

参数: factory -- 可用于实例化日志记录的工厂调用。

3.2 新版功能: 此功能与 getLogRecordFactory() ，以允许开发人员更多地控制 LogRecord 构造了表示日志事件的。

工厂有以下签名：

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

名称

记录器名称。

水平

日志记录级别（数字）。

FN

进行日志记录调用的文件的完整路径名。

洛诺

进行日志记录调用的文件中的行号。

味精

日志消息。

阿尔茨海默病

日志消息的参数。

exc_info

异常元组，或 None .

芬克

调用日志记录调用的函数或方法的名称。

辛福

堆栈回溯，如由提供的 traceback.print_stack() ，显示调用层次结构。

关键字参数

其他关键字参数。

模块级属性¶

logging.lastResort¶: “最后的处理程序”可通过此属性使用。这是一个 StreamHandler 写信给 sys.stderr 具有一定水平的 WARNING ，用于在没有任何日志配置的情况下处理日志事件。最终结果是将消息打印到 sys.stderr . 这将替换前面的错误消息，即“找不到记录器XYZ的处理程序”。如果你出于某种原因需要更早的行为， lastResort 可以设置为 None .

3.2 新版功能.

与警告模块集成¶

这个 captureWarnings() 函数可用于集成 logging 与 warnings 模块。

logging.captureWarnings(capture)¶

此函数用于通过登录和关闭来关闭警告捕获。

如果捕获是 True ，由发布的警告 warnings 模块将被重定向到日志记录系统。具体来说，警告的格式将使用 warnings.formatwarning() 并将生成的字符串记录到名为 'py.warnings' 严重程度为 WARNING .

如果捕获是 False ，将停止将警告重定向到日志记录系统，并将警告重定向到其原始目标（即以前有效的目标）。 captureWarnings(True) 被称为。

参见

模块 logging.config: 日志模块的配置API。
模块 logging.handlers: 日志模块中包含有用的处理程序。
PEP 282 -测井系统: 描述此特性以包含在Python标准库中的建议。
Original Python logging package: 这是 logging 包裹。此站点提供的包版本适用于python 1.5.2、2.1.x和2.2.x，其中不包括 logging 在标准库中打包。

`logging` ——python的日志记录工具¶

记录器对象¶

测井水平¶

处理对象¶

格式化程序对象¶

过滤对象¶

日志记录对象¶

日志记录属性¶

loggeradapter对象¶

线程安全性¶

模块级功能¶

模块级属性¶

与警告模块集成¶

Table of Contents

上一个主题

下一个主题

logging ——python的日志记录工具¶

记录器对象¶

测井水平¶

处理对象¶

格式化程序对象¶

过滤对象¶

日志记录对象¶

日志记录属性¶

loggeradapter对象¶

线程安全性¶

模块级功能¶

模块级属性¶

与警告模块集成¶

`logging` ——python的日志记录工具¶