logging

重要

此页面包含API参考信息。有关更高级主题的教程信息和讨论，请参阅

• 基本教程

• 高级教程

• 记录手册

源代码： Lib / logging / __init__.py

2.3版本的新功能。

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

使用标准库模块提供的日志API的主要好处是，所有Python模块都可以参与日志记录，因此您的应用程序日志可以包含自己的消息，并与第三方模块的消息进行集成。

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

下面列出了模块定义的基本类及其功能。

• 记录器公开应用程序代码直接使用的接口。

• 处理程序将日志记录（由记录器创建）发送到相应的目标。

• 过滤器提供更精细的设备来确定要输出的日志记录。

• 格式化程序指定最终输出中日志记录的布局。

1.记录器对象

记录器具有以下属性和方法。请注意，记录器不会直接实例化，而是始终通过模块级功能进行实例化logging.getLogger(name)。多次调用getLogger()具有相同的名称将始终返回对同一个Logger对象的引用。

该名称可能是由句点分隔的分层值，例如foo.bar.baz（尽管它也可能仅仅是普通的foo）。 在分层列表中更靠后的记录器是列表中较高记录器的子记录器。 例如，给定一个名为foo的记录器，名称为foo.bar，foo.bar.baz和foo.bam的记录器都是foo的后代。 记录器名称层次结构类似于Python包层次结构，如果使用推荐的构造logging.getLogger（__ name__）以每个模块为基础组织记录器，则相同。 这是因为在模块中，__name__是Python包命名空间中的模块名称。

class logging.LoggerLogger.propagate

如果这个计算结果为true，那么记录到这个记录器的事件将被传递给更高级（祖先）记录器的处理程序，除了附加到这个记录器的任何处理程序。消息直接传递给祖先记录器的处理程序 - 既不考虑祖先记录器的级别也不考虑过滤器。

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

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

注意

如果将处理程序附加到记录器及其一个或多个其祖先，它可能会多次发出相同的记录。 一般情况下，您不需要将处理程序附加到多个记录器 - 如果您只将它附加到记录器层次结构中最高的相应记录器，那么它会看到所有后裔记录器记录的所有事件，前提是它们的传播 设置被设置为True。 一种常见的情况是仅将处理程序附加到根记录器，并让传播处理其余部分。

Logger.setLevel(lvl)

将此记录器的阈值设置为lvl。 记录不如lvl严重的消息将被忽略。 当创建记录器时，级别设置为NOTSET（当记录器是根记录器时会导致所有消息处理，或者当记录器是非根记录器时将其委派给父项）。 请注意，根记录器是使用级别WARNING创建的。

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

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

如果达到根目录，并且其级别为NOTSET，则将处理所有消息。否则，根的级别将被用作有效级别。

请参阅记录级别以获取级别列表。

Logger.isEnabledFor(lvl)

指示是否将由此记录器处理严重性级别为lvl的消息。这种方法首先检查由设置的模块级别级别logging.disable(lvl)，然后检查记录器的有效级别getEffectiveLevel()。

Logger.getEffectiveLevel()

指示此记录器的有效等级。 如果使用setLevel（）设置了NOTSET以外的值，则返回该值。 否则，层次结构遍历到根，直到找到NOTSET以外的值，并返回该值。 返回的值是一个整数，通常是logging.DEBUG，logging.INFO等之一。

Logger.getChild(suffix)

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

2.7版本的新功能。

Logger.debug(msg, *args, **kwargs)

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

在被检查的kwargs中有两个关键字参数：exc_info，如果它不计算为false，则会导致异常信息被添加到日志消息中。 如果提供了一个异常元组（以sys.exc_info（）返回的格式），则使用它; 否则，调用sys.exc_info（）来获取异常信息。

第二个关键字参数是额外的，它可以用来传递一个字典，该字典用于使用用户定义的属性填充为记录事件创建的LogRecord的__dict__。这些自定义属性可以随意使用。例如，它们可以合并到记录的消息中。例如：

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已经用LogRecord属性字典中的'clientip'和'user'设置了一个格式字符串。如果缺少这些信息，将不会记录该消息，因为会出现字符串格式异常。所以在这种情况下，你总是需要用这些键传递额外的字典。

虽然这可能很烦人，但此功能旨在用于特殊情况下，例如多线程服务器，其中相同的代码在许多环境中执行，并且产生的有趣情况取决于此环境（如远程客户端IP地址和经过身份验证用户名，在上面的例子中）。在这种情况下，专门的Formatters可能会与特定的Handlers 一起使用。

Logger.info(msg, *args, **kwargs)

在此记录器上记录INFO级别的消息。 参数解释为debug（）。

Logger.warning(msg, *args, **kwargs)

WARNING在此记录器上记录一级消息。参数被解释为debug()。

Logger.error(msg, *args, **kwargs)

在此记录器上记录级别为ERROR的消息。 参数解释为debug（）。

Logger.critical(msg, *args, **kwargs)

在此记录器上记录级别为CRITICAL的消息。 参数解释为debug（）。

Logger.log(lvl, msg, *args, **kwargs)

在此记录器上记录具有整数级别lvl的消息。其他参数解释为debug()。

Logger.exception(msg, *args, **kwargs)

在此记录器上记录级别为ERROR的消息。 参数被解释为debug（），除了没有检查到任何传递的exc_info。 异常信息始终添加到日志消息中。 该方法只能从异常处理程序调用。

Logger.addFilter(filt)

将指定的过滤器filt 添加到此记录器。

Logger.removeFilter(filt)

从此记录器中移除指定的过滤器flit 。

Logger.filter(record)

将记录器的过滤器应用于记录，并在记录要处理时返回真值。依次查阅过滤器，直到其中一个返回错误值。如果它们中没有一个返回错误值，则记录将被处理（传递给处理程序）。如果返回一个假值，则不会进一步处理该记录。

Logger.addHandler(hdlr)

将指定的处理程序hdlr添加到此记录器。

Logger.removeHandler(hdlr)

从此记录器中移除指定的处理程序hdlr。

Logger.findCaller()

查找调用者的源文件名和行号。以3元素元组的形式返回文件名，行号和函数名。

在版本2.4中更改：添加了函数名称。在早期版本中，文件名和行号作为2元素元组返回。

Logger.handle(record)

通过将记录传递给与此记录器及其祖先相关联的所有处理程序来处理记录（直到找到错误的传播值）。此方法用于从套接字接收的未识别记录以及本地创建的记录。记录器级别过滤使用filter()。

Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None)

这是一个厂方法，可以在子类中重写以创建专用LogRecord实例。

在版本2.5中更改：添加了func和extra。

2.记录级别

日志级别的数值在下表中给出。如果你想定义你自己的水平，并且需要它们具有相对于预定义水平的特定值，这些主要是感兴趣的。如果您使用相同的数值定义一个级别，它会覆盖预定义的值; 预定义的名称将丢失。

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

3.处理程序对象

处理程序具有以下属性和方法。 请注意，Handler从不直接实例化; 这个类作为更有用的子类的基础。 但是，子类中的__init __（）方法需要调用Handler .__ init __（）。

Handler.__init__(level=NOTSET)

Handler通过设置其级别来初始化实例，将过滤器列表设置为空列表并创建一个锁（使用createLock()）来序列化对I / O机制的访问。

Handler.createLock()

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

Handler.acquire()

获取创建的线程锁createLock()。

Handler.release()

释放通过获取的线程锁acquire()。

Handler.setLevel(lvl)

将此处理程序的阈值设置为lvl。记录不如lvl严重的消息将被忽略。当创建一个处理程序时，级别设置为NOTSET（这会导致处理所有消息）。

请参阅记录级别以获取级别列表。

Handler.setFormatter(form)

设置Formatter此处理程序以形成。

Handler.addFilter(filt)

将指定的过滤器filt 添加到此处理程序。

Handler.removeFilter(filt)

从该处理程序中删除指定的过滤器filt 。

Handler.filter(record)

如果要处理记录，则将此处理程序的过滤器应用于记录并返回真值。依次查阅过滤器，直到其中一个返回错误值。如果它们中没有一个返回错误值，则记录将被发射。如果返回一个假值，处理程序不会发出记录。

Handler.flush()

确保所有日志记录输出已被刷新。这个版本什么都不做，并且打算由子类来实现。

Handler.close()

整理处理程序使用的所有资源。该版本没有输出，但是从处理程序的内部列表中删除处理程序，处理程序在shutdown()被调用时关闭。子类应该确保这个被覆盖的close()方法调用。

Handler.handle(record)

根据可能已添加到处理程序的过滤器，有条件地发出指定的日志记录。采集/释放I / O线程锁包裹记录的实际排放。

Handler.handleError(record)

当在emit（）调用期间遇到异常时，应该从处理程序调用此方法。 如果模块级属性raiseExceptions为False，那么异常将被忽略。 这就是日志系统最需要的东西 - 大多数用户不会在意日志系统中的错误，他们更关心应用程序错误。 但是，如果您愿意，可以用自定义处理程序替换它。 指定的记录是发生异常时正在处理的记录。 （raiseExceptions的默认值为True，因为这在开发过程中更有用）。

Handler.format(record)

格式化记录 - 如果设置了格式化程序，请使用它。否则，请使用该模块的默认格式化程序。

Handler.emit(record)

做任何事情来实际记录指定的日志记录。此版本旨在由子类实现，因此引发了一个NotImplementedError。

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

4.格式化对象

格式化对象具有以下属性和方法。 他们负责将LogRecord转换为（通常）一个可以由人工或外部系统解释的字符串。 基本格式化程序允许指定格式化字符串。 如果没有提供，则使用'％（message）s'的默认值，该值仅包含日志调用中的消息。 要在格式化输出中添加更多信息（如时间戳），请继续阅读。

格式化程序可以使用格式化字符串进行初始化，该格式化字符串利用LogRecord属性的知识 - 例如上面提到的默认值，利用用户的消息和参数预先格式化为LogRecord的消息属性的事实。 这个格式字符串包含标准的Python％风格的映射键。 有关字符串格式的更多信息，请参阅字符串格式化操作一节。

aLogRecord中有用的映射键在LogRecord属性部分给出。

class logging.Formatter(fmt=None, datefmt=None)

返回类的新实例Formatter。该实例初始化为整个消息的格式字符串，以及消息的日期/时间部分的格式字符串。如果没有指定fmt，'%(message)s'则使用。如果未指定datefmt，则使用ISO8601日期格式。

format(record)

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

formatTime(record, datefmt=None)

这个方法应该由格式化程序从格式（）中调用，该格式化程序要使用格式化的时间。 在格式化程序中可以重写此方法以提供任何特定要求，但基本行为如下所示：如果指定了datefmt（字符串），它将与time.strftime（）一起使用来格式化记录的创建时间。 否则，使用ISO8601格式。 结果字符串被返回。

该函数使用用户可配置的函数将创建时间转换为元组。 默认情况下，使用time.localtime（）; 要为特定格式化程序实例更改此设置，请将转换器属性设置为与time.localtime（）或time.gmtime（）具有相同签名的函数。 要为所有格式化程序进行更改，例如，如果希望以GMT格式显示所有记录时间，请在Formatter类中设置转换器属性。

formatException(exc_info)

将指定的异常信息（由sys.exc_info（）返回的标准异常元组）格式化为一个字符串。 这个默认实现只使用traceback.print_exception（）。 结果字符串被返回。

5.过滤对象

处理程序和记录器可以使用过滤器进行比级别提供的更复杂的过滤。 基本过滤器类只允许记录器层次结构中某个点以下的事件。 例如，用“A.B”初始化的过滤器将允许由记录器“A.B”，“ABC”，“ABCD”，“ABD”等记录的事件，但不允许“A.BB”，“BA B'等。如果用空字符串初始化，所有事件都会被传递。

class logging.Filter(name='')

返回Filter类的一个实例。 如果指定了名称，则会命名一个记录器，该记录器与其子项一起通过过滤器允许其事件。 如果name是空字符串，则允许每个事件。

filter(record)

指定的记录是否被记录？对于no返回零，对于yes返回非零。如果认为合适，记录可以通过这种方法在原地进行修改。

请注意，在处理程序发出事件之前，会查看附加到处理程序的过滤器，而在事件发送给处理程序之前（无论使用debug（），info（）等）何时记录事件，都会查询连接到记录器的过滤器。 这意味着由后代记录器生成的事件不会被记录器的过滤器设置过滤，除非过滤器也已应用于这些后代记录器。

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

虽然过滤器主要用于根据比级别更复杂的标准过滤记录，但他们可以看到每个由它们所连接的处理程序或记录程序处理的记录：如果您想要执行诸如计算多少个记录记录由特定的记录器或处理程序处理，或者在正在处理的LogRecord中添加，更改或删除属性。显然，改变LogRecord需要谨慎处理，但它确实允许将上下文信息注入日志中（请参阅使用过滤器来传递上下文信息）。

6. LogRecord对象

每次记录日志时，LogRecord实例都由Logger自动创建，并且可以通过makeLogRecord（）手动创建（例如，通过线路接收的pickled事件）。

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

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

主要信息通过msg和args传递，它们使用msg％args进行组合，以创建记录的消息字段。

参数：	name - 用于记录由此LogRecord表示的事件的记录器的名称。请注意，该名称将始终具有此值，即使它可能由连接到其他（祖先）记录器的处理程序发出。level - 日志记录事件的数字级别（DEBUG，INFO等之一）请注意，这将转换为LogRecord的两个属性：levelno作为相应级别名称的数字值和级别名称。路径名 - 进行日志记录调用的源文件的完整路径名。lineno - 进行日志记录调用的源文件中的行号。msg - 事件描述消息，可能是一个带有变量数据占位符的格式字符串。args - 要合并到msg参数中的变量数据以获取事件描述。exc_info - 包含当前异常信息的异常元组，如果没有例外信息可用，则为None。func - 调用日志记录调用的函数或方法的名称。

• name - 用于记录由此LogRecord表示的事件的记录器的名称。请注意，该名称将始终具有此值，即使它可能由连接到其他（祖先）记录器的处理程序发出。

• 级别 - 日志事件的数字级别（DEBUG，INFO等之一）请注意，这将转换为LogRecord的两个属性：levelno数值和levelname相应级别名称。

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

• lineno - 进行日志记录调用的源文件中的行号。

• msg - 事件描述消息，可能是一个带有变量数据占位符的格式字符串。

• args - 要合并到msg参数中的变量数据以获取事件描述。

• exc_info - 包含当前异常信息的异常元组，或者没有可用的异常信息则为None

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

在版本2.5中更改：添加了func。

getMessage()

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

7. LogRecord属性

LogRecord有许多属性，其中大部分属性都是从构造函数的参数派生而来的。（请注意，名称并不总是与LogRecord构造函数参数和LogRecord属性完全对应。）这些属性可用于将记录中的数据合并到格式字符串中。下表按字母顺序列出了属性名称，它们的含义以及％-style格式字符串中相应的占位符。

属性名称	格式	描述
ARGS	你不需要自己设置格式。	参数元组被合并到msg中以产生消息，或者其值被用于合并的词典（当只有一个参数时，它是一个字典）。
asctime	％（asctime）类	LogRecord创建时的可读时间。默认情况下，这是'2003-07-08 16：49：45,896'的格式（逗号之后的数字是毫秒部分）。
created	％（created）的F	LogRecord创建的时间（由time.time（）返回）。
exc_info	你不需要自己设置格式。	异常元组（àla sys.exc_info）或，如果没有发生异常，则为无。
filename	％（filename）类	路径名的文件名部分。
funcName	％（funcName）类	包含日志记录调用的函数的名称。
levelname	％（levelname）■	文本消息级别（'DEBUG'，'INFO'，'WARNING'，'ERROR'，'CRITICAL'）。
levelno	％（levelno）s	消息的数字记录级别（DEBUG，INFO，WARNING，ERROR，CRITICAL）。
LINENO	％（LINENO）d	发出日志记录调用的源行号（如果可用）。
module	％（module）类	模块（文件名称部分）。
msecs	％（msecs）d	LogRecord创建时的毫秒部分。
message	％（message）类	记录的消息，计算为msg％args。这是在调用Formatter.format（）时设置的。
msg	你不需要自己设置格式。	在原始日志记录调用中传递的格式字符串。与args合并生成消息或任意对象（请参阅使用任意对象作为消息）。
name	％（nae）类	用于记录呼叫的记录器的名称。
pathname	％（filename）类	发出日志记录调用的源文件的完整路径名（如果可用）。
process	％（process）d	进程ID（如果可用）。
processName	％（processName）类	进程名称（如果可用）。
relativeCreated	％（relativeCreated）d	相对于加载日志记录模块的时间，LogRecord创建时的时间（以毫秒为单位）。
thread	％（thread）d	线程ID（如果可用）。
threadName	％（threadName）类	线程名称（如果可用）。

在版本2.5中更改：添加了funcName。

在版本2.6中更改：processName被添加。

8. LoggerAdapter对象

LoggerAdapter实例用于方便地将上下文信息传递到日志记录调用中。有关使用示例，请参阅有关向日志输出添加上下文信息的部分。

2.6版本中的新功能。

class logging.LoggerAdapter(logger, extra)

返回LoggerAdapter的一个实例，它使用底层的Logger实例和类字典对象进行初始化。

process(msg, kwargs)

修改传递给日志记录调用的消息和/或关键字参数以插入上下文信息。该实现将对象作为额外 传递给构造函数，并使用'extra'关键字将其添加到kwargs。返回值是一个（msg，kwargs）元组，它具有传入的参数（可能是修改的）版本。

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

在版本2.7中更改：该isEnabledFor()方法已添加到LoggerAdapter。此方法委托给基础记录器。

9.线程安全

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

如果使用信号模块实现异步信号处理程序，则可能无法在此类处理程序中使用日志记录。 这是因为线程模块中的锁实现并不总是可重入的，所以不能从这些信号处理程序中调用。

10.模块级功能

除了上述类别之外，还有许多模块级别的功能。

logging.getLogger([name])

返回一个具有指定名称的记录器，或者如果没有指定名称，则返回一个记录器，该记录器是层次结构的根记录器。如果指定，名称通常是点分隔的分层名称，如“a”，“ab”或“abcd”。这些名称的选择完全取决于正在使用日志记录的开发人员。

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

logging.getLoggerClass()

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

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

logging.debug(msg[, *args[, **kwargs]])

DEBUG在根记录器上记录具有级别的消息。该MSG是消息格式字符串，并且ARGS是被合并到参数MSG使用字符串格式化操作。（请注意，这意味着您可以使用格式字符串中的关键字以及单个字典参数。）

在被检查的kwargs中有两个关键字参数：exc_info，如果它不计算为false，则会导致异常信息被添加到日志消息中。 如果提供了一个异常元组（以sys.exc_info（）返回的格式），则使用它; 否则，调用sys.exc_info（）来获取异常信息。

另一个可选的关键字参数是额外的，它可以用来传递一个字典，该字典用于使用用户定义的属性填充为记录事件创建的LogRecord的__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已经用LogRecord属性字典中的'clientip'和'user'设置了一个格式字符串。如果缺少这些信息，将不会记录该消息，因为会出现字符串格式异常。所以在这种情况下，你总是需要用这些键传递额外的字典。

虽然这可能很烦人，但此功能旨在用于特殊情况下，例如多线程服务器，其中相同的代码在许多环境中执行，并且产生的有趣情况取决于此环境（如远程客户端IP地址和经过身份验证用户名，在上面的例子中）。在这种情况下，专门的Formatters可能会与特定的Handlers 一起使用。

在版本2.5中更改：添加extra。

logging.info(msg[, *args[, **kwargs]])

在根记录器上记录INFO级别的消息。 参数解释为debug（）。

logging.warning(msg[, *args[, **kwargs]])

WARNING在根记录器上记录具有级别的消息。参数被解释为debug()。

logging.error(msg[, *args[, **kwargs]])

ERROR在根记录器上记录具有级别的消息。参数被解释为debug()。

logging.critical(msg[, *args[, **kwargs]])

CRITICAL在根记录器上记录具有级别的消息。参数被解释为debug()。

logging.exception(msg[, *args[, **kwargs]])

在根记录器上记录级别为ERROR的消息。 参数被解释为debug（），除了没有检查到任何传递的exc_info。 异常信息始终添加到日志消息中。 这个函数只能从异常处理程序中调用。

logging.log(level, msg[, *args[, **kwargs]])

在根记录器上记录具有级别级别的消息。其他参数解释为debug()。

Note

上述模块级别的便利功能（委托给根记录器）调用basicConfig（）以确保至少有一个处理程序可用。 因此，除非在线程启动之前至少有一个处理程序已添加到根日志记录程序中，否则不应在线程中使用它们，也不应在2.7.1和3.2之前的Python版本中使用它们。 在Python的早期版本中，由于basicConfig（）中存在线程安全性缺陷，这可能会（在极少数情况下）导致处理程序被多次添加到根记录器，这又可能导致同一事件发生多条消息。

logging.disable(lvl)

为所有记录器提供优先级高于记录器自身等级的重写级别lvl。 当需要暂时限制整个应用程序的日志记录输出时，此功能可能很有用。 其效果是禁用所有严重级别为lvl及以下的日志记录调用，以便如果使用INFO值调用它，则所有INFO和DEBUG事件都将被丢弃，而严重级别为WARNING及以上的则会根据记录器的 有效水平。 如果调用logging.disable（logging.NOTSET），它将有效地消除这个覆盖级别，以便日志输出再次取决于各个日志记录器的有效级别。

logging.addLevelName(lvl, levelName)

将级别lvl与文本levelName在内部字典中相关联，该内部字典用于将数字级别映射为文本表示，例如，格式化程序格式化消息时。 这个功能也可以用来定义你自己的水平。 唯一的约束是所有使用的级别都必须使用这个函数进行注册，级别应该是正整数，并且应该按照严重性的增加顺序增加。

注意

如果您正在考虑定义自己的关卡，请参阅关于自定义关卡的部分。

logging.getLevelName(lvl)

返回日志级别lvl的文本表示。 如果该级别是预定义级别CRITICAL，ERROR，WARNING，INFO或DEBUG中的一个，则会得到相应的字符串。 如果使用addLevelName（）将名称关联到级别，则返回与lvl关联的名称。 如果传入一个对应于其中一个定义的级别的数值，则返回相应的字符串表示。 否则，返回字符串“Level％s”％lvl。

注意

例如，应使用整数级别。 设置记录器和处理程序实例的级别。 此函数用于通过％（levelname）s格式说明符（请参阅LogRecord属性）在格式化日志输出中显示的整数级别和级别名称之间进行转换。

logging.makeLogRecord(attrdict)

创建并返回一个新的LogRecord实例，其属性由attrdict定义。 此函数对于获取通过套接字发送的pickled LogRecord属性字典并在接收端将其重组为LogRecord实例很有用。

logging.basicConfig([**kwargs])

通过创建具有默认格式化程序的StreamHandler并将其添加到根记录器来进行日志记录系统的基本配置。 如果没有为根记录器定义处理程序，函数debug（），info（），warning（），error（）和critical（）将自动调用basicConfig（）。

如果根记录器已经为它配置了处理程序，该函数不会执行任何操作。

在版本2.4中更改：以前，basicConfig()没有采取任何关键字参数。

注意

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

以下关键字参数均受支持。

格式	描述
文件名	指定使用指定的文件名而不是StreamHandler创建FileHandler。
filemod	指定打开文件的模式，如果指定了filename（如果文件模式未指定，则默认为'a'）。
格式	为处理程序使用指定的格式字符串。
datefmt	使用指定的日期/时间格式。
level	将根记录器级别设置为指定级别。
stream	使用指定的流来初始化StreamHandler。请注意，这个参数与'filename'不兼容 - 如果两者都存在，'stream'将被忽略。

logging.shutdown()

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

logging.setLoggerClass(klass)

在实例化记录器时告诉日志记录系统使用类klass。 该类应该定义__init __（），这样只需要一个名称参数，并且__init __（）应该调用Logger .__ init __（）。 在需要使用自定义记录器行为的应用程序实例化任何记录器之前，通常会调用此函数。

11.与警告模块集成

该captureWarnings()功能可用于logging与warnings模块集成。

logging.captureWarnings(capture)

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

如果capture为True，则警告模块发出的警告将被重定向到日志记录系统。 具体来说，将使用warnings.formatwarning（）格式化警告，并将结果字符串记录到名为“py.warnings”的记录器，其严重程度为WARNING。

如果capture 是False，则警告重定向到日志记录系统将停止，并且警告将被重定向到它们的原始目的地（即，之前有效的那些目标captureWarnings(True)被调用）。

扩展内容

模块logging.config记录模块的配置API。 Module logging.handlers记录模块附带的有用处理程序。 PEP 282 - 日志记录系统描述此功能以包含在Python标准库中的建议。 原始Python日志记录程序包这是日志程序包的原始源代码。 可从此站点获得的软件包版本适用于Python 1.5.2,2.1.x和2.2.x，它们不包括标准库中的日志记录软件包。