logging– Python的记录工具

源代码: Lib / logging / __ init__.py


此模块定义实现灵活的功能和类应用程序和库的事件日志系统.

使用标准库模块提供的日志记录API的关键好处是所有Python模块都可以参与日志记录,因此您的应用程序日志可以包含您自己的消息,这些消息集成了来自第三方的消息partymodules.

该模块提供了许多功能和灵活性。如果您不熟悉日志记录,最好的方法就是查看教程(参见右侧的链接).

模块定义的基本类及其功能如下所示。

  • 记录器公开应用程序代码直接使用的接口.
  • Handlers将日志记录(由记录器创建)发送到适当的目的地.
  • 过滤器提供了一个更细粒度的工具来确定输出哪个日志记录.
  • 格式化在最终输出中指定日志记录的布局.

 

Logger Objects

记录器具有以下属性和方法。请注意,Logger永远不会直接实例化,而是始终通过模块级函数logging.getLogger(name)。多次拨打getLogger()with samename将始终返回对同一Logger对象的引用.

name可能是一个以句点分隔的层次值,如foo.bar.baz(尽管它也可能只是平原foo例如)。在分层列表中向下的记录器是列表中的loggershigher的子项。例如,给定一个名为的记录器foo,名称为的记录器foo.bar, foo.bar.bazfoo.bam都是foo。记录器名称层次结构类似于Pythonpackage层次结构,如果您使用建议的结构logging.getLogger(__name__)在aper-module基础上组织记录器,则与它相同。这是因为在一个模块中,__name__是Python包命名空间中的模块名称.

class logging.Logger
propagate
如果此属性的计算结果为true,则记录到此记录器的事件将被传递给更高级别的处理程序(祖先)记录器,以及附加到此记录器的任何处理程序。消息直接传递给theancestor记录器的处理程序 – 既不考虑有问题的祖先记录器的级别也没有过滤器.

如果计算结果为false,则记录消息不会传递给祖先记录器的处理程序.

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

注意

如果将处理程序附加到记录器and一个或多个它们可以多次发出相同的记录。通常,您不需要将处理程序附加到多个记录器 – 如果您只是将其连接到loggerhierarchy中最高的相应记录器,那么它将看到所有后代记录器记录的所有事件,前提是它们的传播设置已保留调成 True。commonscenario是仅将处理程序附加到根记录器,并让传播处理其余部分.

setLevel (level)
设置此记录器的阈值level。记录比严重的消息level将被忽略;记录严重性为level除非处理程序的级别设置为比更高的严重级别,否则处理程序或处理程序将为此记录程序提供服务或更高级别level.

创建记录器时,级别设置为NOTSET(这会导致在记录器是根记录器时处理所有消息,或者在记录器是非根记录器时委托给父记录)。请注意,使用级别WARNING.

创建的根loggeris术语“委托给父级”意味着如果记录器的级别为NOTSET,则会遍历其祖先记录器链,直到找到与NOTSET以外的级别的祖先为止或者到达了根.

如果发现祖先的级别不是NOTSET,那么祖先的级别被视为祖先搜索的记录器的有效级别,并用于确定如何处理日志事件

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

查看记录级别获取级别列表

更改版本3.2: level参数现在接受级别的字符串表示,例如’INFO‘,作为整数常量的替代,例如INFO。但是,请注意,级别在内部存储为整数,以及诸如getEffectiveLevel()isEnabledFor()将返回/期望通过整数.

isEnabledFor (lvl)
表示如果发出严重性的消息lvl将由此记录器处理。此方法首先检查由logging.disable(lvl)设置的模块级别级别,然后检查由getEffectiveLevel().
getEffectiveLevel)确定的记录器的有效级别
表示此记录器的有效级别。如果使用NOTSET设置了setLevel()以外的值,则返回该值。否则,将遍历层次结构,直到找到除NOTSET以外的值,并返回该值。返回的值是整数,通常是logging.DEBUG, logging.INFOetc.
getChild(suffix)
中的一个记录器,它是该记录器的后代,如确定的那样通过后缀。因此,logging.getLogger("abc").getChild("def.ghi")将返回与logging.getLogger("abc.def.ghi")。这是一种方便的方法,当使用例如父命名记录器命名父记录器时非常有用。__name__而不是文字字符串.

新版本3.2.

debug (msg, *args, **kwargs)
用水平记录消息DEBUG在这个记录器上。msg是主题格式字符串,args是使用字符串格式化运算符合并到msg的参数。(注意,这意味着您可以使用格式字符串中的关键字以及单个字典参数。)

kwargs中有三个关键字参数被检查:exc_info, stack_infoextra.

如果exc_info没有评估为false,则会导致异常信息被添加到日志消息中。如果提供了异常元组(以sys.exc_info()返回的格式)或异常实例,则使用它;否则,调用sys.exc_info()来获取异常信息.

第二个可选的关键字参数是stack_info,默认为False。如果为true,则将堆栈信息添加到loggingmessage,包括实际的日志记录调用。请注意,这与通过指定exc_info显示的堆栈信息不同:Theformer是从堆栈底部到当前线程中的日志记录调用的堆栈帧,而后者是有关已展开的堆栈帧的信息,在异常之后,搜索forexception handlers.

你可以独立于stack_info指定exc_info,例如只是显示你的代码中的某个点,即使没有例外。堆栈框架打印在标题行后面,上面写着:

Stack (most recent call last):

这模仿了Traceback (most recent call last):用于显示异常帧的情况.

第三个关键字参数是extra可用于传递adictionary,用于填充使用用户定义的属性为日志记录事件创建的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

的字典extra传入的字典中的键不应与日志系统使用的键冲突。(有关日志记录系统使用哪些密钥的更多信息,请参阅Formatter文档。)

如果您选择在记录的消息中使用这些属性,则需要进行实际操作。例如,在上面的例子中,Formatter已经设置了一个格式字符串,该字符串在LogRecord的attributesictionary中需要’clientip’和’user’。如果缺少这些消息,则不会显示消息,因为将发生字符串格式化异常。所以在这种情况下,你总是需要用这些键传递extra字典.

虽然这可能很烦人,但此功能旨在用于专业环境,例如多线程服务器,其中相同的代码在多个上下文中执行,并且出现的有趣条件依赖于此上下文(例如远程客户端IP地址和经过身份验证的用户名,在上面的例子中)。在这种情况下,很可能是专门的Formatters将特别使用Handlers.

版本3.2中的新功能:stack_info参数被添加了

在版本3.5中更改:exc_info参数现在可以接受异常实例了

infomsg, *args, **kwargs
在此记录器记录级别为INFO的消息。这些参数被解释为debug().
warningmsg, *args, **kwargs
用级别WARNING在这个记录器上。这些论点被解释为debug().

注意

有一个过时的方法warn这在功能上与warning。作为warn不推荐使用,请不要使用 – 使用warning相反.

error (msg, *args, **kwargs
在这个记录器上记录一个等级为ERROR的信息。这些参数被解释为debug().
criticalmsg, *args, **kwargs
用级别CRITICAL在这个记录器上。参数解释为debug().
loglvl, msg, *args, **kwargs
在此记录器上记录整数级lvl的消息。其他论点是解释为debug().
exceptionmsg, *args, **kwargs
在此记录器上记录级别为ERROR的消息。这些论点被解释为debug()。将异常信息添加到loggingmessage中。只应从异常处理程序调用此方法.
addFilterfilter
将指定的过滤器filter添加到此记录器中
removeFilter// (filter)
删除指定过滤器filter来自这个记录器
filter// (record)
将此记录器的过滤器应用于记录,如果要处理该记录,则返回true值。依次查阅过滤器,直到其中一个返回假值。如果它们都没有返回false值,则将处理记录(传递给处理程序)。如果返回假值,则进一步处理记录.
addHandlerhdlr
将指定的处理程序hdlr添加到此记录器中
removeHandler// (hdlr)
删除指定处理程序hdlr来自此记录器
findCaller// (stack_info=False )
查找呼叫者的源文件名和行号。以4元素元组的形式返回文件名,亚麻,函数名和堆栈信息。堆栈信息以None返回,除非stack_infoTrue.
handlerecord
通过将记录传递给与此记录器相关的所有处理程序和祖先来处理记录(直到错误值为propagate被发现)。此方法用于从套接字接收的unpickled记录,以及本地创建的记录。使用filter().
makeRecordname, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None
这是一个工厂方法,可以在子类中重写以创建特殊的LogRecord实例
hasHandlers// (
检查此记录器是否配置了任何处理程序。这是通过查看此记录器中的处理程序及其在记录器层次结构中的父项来完成的。如果找到处理程序,则返回True,否则False。每当找到“propagate”属性设置为tofalse的记录器时,该方法就会停止搜索层次结构 – 这将是检查处理程序是否存在的最后一个记录器.

新版本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().
setLevellevel
将此处理程序的阈值设置为level。记录比严重的消息level将被忽略。创建处理程序时,将level设置为NOTSET(导致所有消息都被处理).

参见记录级别获取列表levels.

更改版本3.2: level参数现在接受级别的字符串表示,如’INFO‘,作为整数常量的替代,如INFO.

setFormatterfmt
设置Formatter这个处理程序fmt.
addFilterfilter
将指定的过滤器filter添加到此处理程序中
removeFilterfilter
从这个处理程序中删除指定的过滤器filter
filter (record)
将此处理程序的过滤器应用于记录,如果要处理该记录,则返回true值。依次查阅过滤器,直到其中一个返回假值。如果它们都没有返回false值,则会发出记录。如果一个返回一个false值,那么处理程序就不会发出那个字符
flush
确保已刷新所有日志记录输出。这个版本什么都不做,并且是由子类实现的.
close ()
整理处理程序使用的任何资源。这个版本没有输出但是从内部处理程序列表中删除处理程序,当shutdown()叫做。子类应该确保调用它来覆盖close()方法
handle// (record
有条件地发出指定的日志记录,具体取决于可能已添加到处理程序的过滤器。包含I / O线程锁的记录的实际发布.
handleErrorrecord
当在emit()调用期间遇到异常时,应该从处理程序调用此方法。如果模块级属性raiseExceptionsFalse,异常会被默默忽略。对于日志系统来说,这几乎是最需要的 – 大多数用户不会关心日志系统中的abouter错误,他们对应用程序错误更感兴趣。但是,如果您愿意,可以使用自定义处理程序替换它。指定的记录是异常发生时正在处理的记录。(默认值raiseExceptionsTrue,因为它在开发过程中更有用).
formatrecord
格式化记录 – 如果设置了格式化程序,请使用它。否则,请使用模块的默认格式化程序.
emit(record)
执行实际记录指定日志记录所需的任何操作。此版本旨在由子类实现,因此引发NotImplementedError.

对于标准包含的处理程序列表,请参阅logging.handlers.

 

格式化程序对象

Formatter对象具有以下属性和方法。它们负责将LogRecord转换为(通常)一个可由人或外部系统解释的字符串。基础Formatter允许指定格式化字符串。如果没有提供,则使用默认值"%(message)s",它只包括日志记录调用中的消息。要在格式化输出中添加其他信息项(例如时间戳),请继续阅读.

格式化程序可以使用格式字符串进行初始化,该字符串利用了LogRecord属性的知识 – 例如上面提到的默认值使用用户的消息和参数预先格式化为LogRecordmessage属性。此格式字符串包含标准的Python%样式映射键。有关字符串格式的详细信息,请参阅 printf-style字符串格式 .

中有用的映射键LogRecordLogRecord属性.

class logging.Formatterfmt=None, datefmt=None, style=”%”
返回Formatter类。实例初始化为消息的格式字符串,以及消息的日期/时间部分的格式字符串。如果没有fmt指定,"%(message)s"用来。如果没有指定datefmt,则使用formatTime()文档中描述的格式

// style参数可以是’%’,'{‘或’$’之一,并确定格式字符串将如何与其数据合并:使用%-formatting,str.format()string.Template之一。见在整个应用程序中使用特定的格式样式有关使用{ – 和$ -formatting日志消息的更多信息

更改版本3.2: style参数被添加了

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

如果有叠加信息,可以在异常信息后附加,如有必要,使用formatStack()进行转换.

formatTimerecord, datefmt=None
这个方法应该从format()由希望使用格式化时间的格式化程序。此方法可以覆盖信息提供者以满足任何特定要求,但基本行为如下:if datefmt(字符串)指定,用于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 class中设置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(用于附加毫秒值).

formatExceptionexc_info
将指定的异常信息(由sys.exc_info()返回的标准异常元组)格式化为字符串。这个默认实现只使用traceback.print_exception()。返回结果字符串
formatStackstack_info)
格式化指定的堆栈信息(traceback.print_stack()返回的字符串,但删除了最后一个换行符)as astring。这个默认实现只返回输入值.

 

Filter Objects

Filters可以被HandlersLoggers用于比级别提供的更复杂的过滤。基本过滤器类仅允许在记录器层次结构中低于某个点的事件。例如,使用’A.B’初始化的过滤器将允许记录器’A.B’,’ABC’,’ABCD’,’ABD’等记录的事件,但不允许’A.BB’,’BAB’等。如果用theempty字符串初始化,则所有事件都被传递.

class logging.Filter (name=””)
返回Filter类的实例。如果指定了name,则为一个记录器命名,该记录器与其子节点一起通过过滤器允许其事件。如果name是空字符串,则允许每个事件.

filter (record
是否记录了指定的记录?对于no,返回零,非零foryes。如果认为合适,可以通过此方法就地修改记录.

注意在处理程序发出事件之前咨询附加到处理程序的过滤器,而无论何时记录事件,都要查阅附加到记录器的过滤器(使用在向处理者发送事件之前,debug(), info()等)。这意味着由后代记录器生成的事件不会被记录器的filtersetting过滤,除非过滤器也已应用于那些后代记录器.

你实际上不需要子类Filter:你可以传递任何具有相同语义的filter方法的实例.

更改版本3.2:你不需要创建专门的Filter类,或者使用带有filter方法的其他类:您可以使用函数(或其他可调用的)作为过滤器。过滤逻辑将检查过滤器对象是否具有filter属性:如果有,则假定为Filter并调用它的filter()方法。否则,它被认为是可调用的并且以记录作为单参数调用。返回值应该与filter().

返回的值一致。尽管过滤器主要用于根据比级别更复杂的标准过滤记录,但它们可以查看由它们附加到的处理程序或记录程序处理的每条记录:如果您想要执行诸如计算特定记录器或处理程序处理的记录数,或者在正在处理的LogRecord中添加,更改或删除属性等操作,则可能很有用。显然改变LogRecord需要小心谨慎,但它确实允许在日志中注入上下文信息(参见使用过滤器来传递上下文信息).

 

LogRecord对象

LogRecord实例是每次记录某事时由Logger自动创建的,并且可以通过makeLogRecord()手动创建(例如,通过电线接收的腌制事件)。

class logging.LogRecordname, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None
包含与被记录事件相关的所有信息.

主要信息在msgargs中传递,使用msg % args组合创建message therecord的字段.

参数:
  • name – 用于记录此LogRecord表示的事件的记录器的名称。请注意,此名称将始终具有此值,即使它可能由附加到不同(祖先)logger的处理程序发出.
  • level – 日志记录事件的数字级别(调试,信息等)请注意,这将转换为two属性的LogRecord:levelno为数值,而levelname为对应的级别名称.
  • pathname – 记录调用的源文件的完整路径名.
  • lineno – 源文件中记录调用的行号.
  • msg – 事件描述消息,可能是带有可变数据占位符的格式字符串.
  • args具有相同签名的函数 – 将变量数据合并到msg获取事件描述的参数.
  • exc_info – 带有当前异常信息的异常元组,或None如果没有异常信息可用.
  • func– 调用日志调用的函数或方法的名称.
  • sinfo– 一个文本字符串,表示当前线程中堆栈底部的堆栈信息,直到记录调用.
getMessage ()
为此返回消息LogRecord将任何用户提供的参数与消息合并后的实例。如果用户提供的日志记录调用的消息参数不是字符串,str()被调用它将它转换为字符串。这允许使用用户定义的类作为消息,其__str__方法可以返回要使用的实际格式字符串.

更改版本3.2:通过提供用于创建记录的工厂,可以更好地配置LogRecord的创建。工厂可以使用getLogRecordFactory()setLogRecordFactory()(请参阅此处了解工厂的签名).

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

old_factory = logging.getLogRecordFactory()

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

logging.setLogRecordFactory(record_factory)

使用此模式,可以链接多个工厂,并且只要它们不会覆盖彼此的属性或无意中覆盖上面列出的标准属性,就应该有nosurprises.

 

LogRecord属性

LogRecord有许多属性,其中大部分都是从构造函数的参数派生出来的。(请注意,名称并不总是在LogRecord构造函数参数和LogRecord属性之间相互对应。)这些属性可用于将记录中的数据合并到格式字符串中。下表列出了(按字母顺序)属性名称,它们的含义以及%-styleformat字符串中相应的占位符.

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

在{} -formatting的情况下,你可以通过放置属性名称来指定格式化标记,分开从它带结肠。例如:{msecs:03d}的aplaceholder会将4的毫秒值格式化为004。有关可用选项的详细信息,请参阅str.format()文档.

属性名称 格式 说明
args 你不应该自己需要toformat. 参数元组合并到msg toproduce message,或者是一个用于合并的dict(当只有一个参数,它是一个字典).
asctime %(asctime)s 创建LogRecord时的人类可读时间。默认情况下,形式为’2003-07-08 16:49:45,896’(逗号之后的数字是时间的毫秒级).
创建 %(created)f 时间LogRecord创建(由time.time()倒回.
exc_info 你不应该自己需要toformat. 例外元组(àlasys.exc_info)或者,如果没有发生异常,None.
文件名 %(filename)s pathname.
funcName的文件名部分 %(funcName)s 包含日志记录调用的函数名称.
levelname %(levelname)s 消息的文本日志记录级别("DEBUG", "INFO", "WARNING","ERROR", "CRITICAL").
levelno %(levelno)s 数字消息的记录级别(DEBUG, INFO,WARNING, ERROR,CRITICAL).
lineno %(lineno)d 记录呼叫发出的源行号(如果可用).
消息 %(message)s 记录的消息,计算为msg %args。这是在调用Formatter.format()时设置的.
模块 %(module)s 模块(filename的名称部分.
mcscs %(msecs)d LogRecord创建时的几分之一.
msg 你不应该自己需要toformat. originallogging调用中传递的格式字符串。合并args toproduce message,或任意对象(参见使用任意对象作为消息).
名称 %(name)s 用于记录呼叫的记录器的名称.
pathname %(pathname)s 发出记录呼叫的源文件的完整路径名(如果可用).
进程 %(process)d 进程ID(如果有).
processName %(processName)s 进程名称(如果可用).
relativeCreated %(relativeCreated)d 创建LogRecord的时间(以毫秒为单位),相对于loggingmodule的加载时间.
stack_info 你不应该自己格式化. 从当前线程中的堆栈底部堆栈帧信息(如果可用),直到并包括日志调用的堆栈帧,这导致该记录的创建.
线 %(thread)d 线程ID(如果有).
threadName %(threadName)s 线程名称(如果有).

在版本3.1中更改:processName加入。

 

LoggerAdapter对象

LoggerAdapter实例用于方便地将上下文信息传递给日志记录调用。有关用法示例,请参阅部分向记录输出添加上下文信息.

class logging.LoggerAdapterlogger, extra
返回LoggerAdapter用aunderunder Logger实例和类似dict的对象初始化.

process (msg, kwargs)
修改传递给日志记录调用的消息和/或关键字参数为了插入上下文信息。这个实现将对象作为extra传递给构造函数,并使用key’extra’将其添加到kwargs。返回值是一个(msg, kwargs)元组,它具有传入的参数的(可能已修改的)版本.

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

更改版本3.2: isEnabledFor(), getEffectiveLevel(),setLevel()hasHandlers()方法被添加到LoggerAdapter。这些方法委托给底层记录器

Thread Safety

日志记录模块旨在是线程安全的,无需客户执行任何特殊工作。它通过使用threadinglocks实现了这一点;有一个锁来序列化对模块共享数据的访问,一个deach处理程序还创建一个锁来序列化对其底层I / O的访问.

如果你使用signal实现异步信号处理程序模块,您可能无法在此类处理程序中使用日志记录。这是因为threading模块中的锁实现并不总是重入,因此无法从这些信号处理程序中调用.

模块 – 级函数

除了类之外如上所述,有许多模块级功能

logging.getLoggername=None)
返回具有指定名称的记录器,或者,如果名称是None,返回alogger,它是层次结构的根记录器。如果指定,名称通常是一个点分隔的分层名称,如‘a’, ‘a.b’‘a.b.c.d’这些名称的选择完全取决于使用日志的开发者.

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

logging.getLoggerClass ( )
返回标准的Logger类,或者传递给setLoggerClass()的最后一个类。可以从新的classdefinition中调用此函数,以确保安装自定义的Loggerclass不会撤消其他代码已经应用的自定义。例如:

class MyLogger(logging.getLoggerClass()):    
# ... override behaviour here
logging.getLogRecordFactory
返回一个用于创建LogRecord.

的可调用的新版本3.2:此功能与setLogRecordFactory()一起提供,允许开发人员更好地控制LogRecord表示日志事件的构造方式.

查看setLogRecordFactory()有关如何调用调用的更多信息.

logging.debug (msg, *args, **kwargs
在根记录器记录级别为DEBUG的消息。msg是主题格式字符串,而args是使用字符串格式化运算符合并到msg的参数。(注意,这意味着您可以使用格式字符串中的关键字以及单个字典参数。)

kwargs中有三个关键字参数被检查:exc_info如果它没有评估为false,则会将异常信息添加到日志消息中。如果提供了异常元组(以sys.exc_info()返回的格式)或异常实例,则使用它;否则,调用sys.exc_info()来获取异常信息.

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

您可以指定stack_info独立于exc_info,例如只是显示你的代码中的某个点,即使没有例外。堆栈框架打印在标题行后面,上面写着:

Stack (most recent call last):

这模仿Traceback (most recent call last):用于显示异常框架.

第三个可选的关键字参数是extra可用于传递adictionary,用于填充使用用户定义的属性为日志记录事件创建的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

字典中的键传入extra不应该与日志系统使用的密钥冲突。(有关日志记录系统使用哪些密钥的更多信息,请参阅Formatter文档。)

如果您选择在记录的消息中使用这些属性,则需要进行实际操作。例如,在上面的例子中,Formatter已经设置了一个格式字符串,该字符串在LogRecord的attributesictionary中需要’clientip’和’user’。如果缺少这些消息,则不会显示消息,因为将发生字符串格式化异常。所以在这种情况下,你总是需要用这些键传递extra字典.

虽然这可能很烦人,但这个功能适用于专门的环境,例如多线程服务器,相同的代码在很多上下文中执行,并且出现的有趣条件依赖于此上下文(例如远程客户端IP地址和经过身份验证的用户名,在上面的示例中)。在这种情况下,很可能是专门的Formatters将特别使用Handlers.

新版本3.2: stack_info参数已添加.

logging.infomsg, *args, **kwargs
用级别INFO在根记录器上。参数解释为debug().
logging.warningmsg, *args, **kwargs
在根记录器记录级别为WARNING的消息。这些论点被解释为debug().

注意

有一个过时的功能warn在功能上与warning相同。由于warn已被弃用,请不要使用 – 使用warning代替.

logging.error (msg, *args, **kwargs
用级别记录消息ERROR在根记录器上。参数解释为debug().
logging.criticalmsg, *args, **kwargs
在根记录器上记录级别为CRITICAL的消息。这些论点被解释为debug().
logging.exceptionmsg, *args, **kwargs
在根记录器上记录级别为ERROR的消息。这些论点被解释为debug()。将异常信息添加到loggingmessage中。只应从异常处理程序调用此函数.
logging.loglevel, msg, *args, **kwargs
记录级别为的消息level在根记录器上。其他参数解释为debug().

注意

上面的模块级便捷函数,委托给rootroger,调用basicConfig()确保至少有一个手柄可用。因此,他们应该not用于线程,在2.7.1和3.2之前的Python版本中,除非至少有一个处理程序添加到根记录器before线程开始了。在早期版本的Python中,由于线程安全性缺点basicConfig(),这可以(在极少数情况下)导致处理程序被多次添加到根记录器,这可以反过来导致同一事件的多个消息.

logging.disable (lvl=CRITICAL )
提供最重要的水平lvl对于所有优先于记录器自身级别的记录器。当需要在整个应用程序中临时限制loggingoutput时,此功能可能很有用。它的作用是禁用所有日志记录调用的严重性lvl以下,所以你用INFO值来称呼它,那么所有INFO和DEBUG事件都会被淘汰,而那些严重性为WARNING及以上的事件将根据记录器的有效水平进行处理。如果logging.disable(logging.NOTSET)被调用,它有效地消除了这个覆盖级别,因此日志输出再次取决于各个记录器的有效级别.

请注意,如果您已定义任何高于的自定义日志记录级别CRITICAL(这不推荐),你将无法依赖于lvl参数,但必须明确提供合适的值.

更改版本3.7: lvl参数默认为CRITICAL。有关此更改的详细信息,请参阅问题#28524。

logging.addLevelNamelvl, levelName)
与文字对应lvl levelName在内部字典中,用于将数字级别映射到文本表示,例如当Formatter格式化消息。此功能还可用于定义您自己的级别。唯一的限制是所有使用的级别都必须使用此函数注册,级别应该是正整数,并且应该按照严重性的递增顺序增加.

注意

如果您正在考虑定义自己的关卡,请参阅自定义级别.

logging.getLevelNamelvl
返回伐木水平的文字表示lvl。如果级别是预定义级别CRITICAL, ERROR, WARNING,INFODEBUG之一,那么您将获得相应的字符串。如果您使用addLevelName()将名称与名称相关联,则表示您与lvl退回。如果传入对应于所定义级别之一的数值,则返回相应的字符串表示。否则,返回字符串’Level%s’%lvl .

注意

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

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

logging.makeLogRecord (attrdict)
创建并返回一个新的LogRecord其属性由attrdict定义的实例。这个函数对于获取一个pickle LogRecord属性字典,通过套接字发送,并在接收端重构为LogRecord实例非常有用.
logging.basicConfig**kwargs
使用默认的StreamHandler创建一个Formatter并将其添加到theroot logger。如果没有为根记录器定义处理程序,debug(), info(), warning(),error()critical()将自动调用basicConfig()

如果根记录器已经为其配置了处理程序,则此函数不执行任何操作.

注意

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

支持以下关键字参数.

格式 描述
filename 指定使用指定的文件名创建FileHandler,而不是aStreamHandler。
filemode 如果filename指定,在这个模式打开文件。Defaultsto "a".
format 使用指定的格式字符串forhandler.
datefmt 使用指定的日期/时间格式,如time.strftime().
style 接受如果format指定后,将此样式用于格式字符串。一个"%","{""$"分别为 printf-style ,str.format()string.Template。默认为"%".
level 设置根记录器级别到指定的级别.
stream 使用指定的流初始化StrehHandler。请注意,这个参数与filename不兼容 – 如果出现bothare,则ValueError被抬起.
handlers 如果指定,这应该是一个可迭代的已创建的处理程序,以添加到rootlogger。任何尚未具有格式化程序集的处理程序将被分配在此函数中创建的默认格式化程序。请注意,此参数与filename要么 stream– 如果出现bothare,ValueError被养了

在版本3.2中更改:style争论被添加了

改版3.3:handlers论点被添加了。附加检查添加了指定不兼容参数的tocatch情况(例如handlersstreamfilename一起,或streamfilename一起).

logging.shutdown
通过刷新和关闭所有处理程序,通知日志记录系统执行有序关闭。这应该在应用程序退出时调用,并且在此调用之后应该进一步使用日志系统.
logging.setLoggerClassklass
告诉日志系统在实例化记录器时使用类klass。类应该定义__init__()以便只需要一个名称参数,__init__()应该叫Logger.__init__()。在通过需要使用自定义记录器行为的应用程序实例化任何记录器之前,通常会调用此函数.
logging.setLogRecordFactoryfactory
设置一个用于创建LogRecord.

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

新版本3.2:已提供此功能, 随着 getLogRecordFactory(),允许开发人员更好地控制LogRecord表示日志事件的构造方式.

工厂有以下签名:

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

name: 记录器名称。
水平: 记录级别(数字).
fn: 记录调用的文件的完整路径名.
lno: 该行记录调用的文件中的数字.
msg: 日志消息.
args: 日志消息的参数。
exc_info: 一个异常元组,或None.
func: 调用loggingcall的函数或方法的名称
sinfo: traceback.print_stack()提供的堆栈回溯,显示调用层次结构.
kwargs: 附加关键字参数

模块级属性

logging.lastResort
通过此属性可以使用“最后的处理程序”。这是StreamHandler写入sys.stderr,其级别为WARNING,用于在没有任何日志配置的情况下处理日志记录事件。最终结果是将消息打印到sys.stderr。这将替换先前的错误消息,指出“无法为记录器XYZ找到处理程序”。如果由于某种原因需要较早的行为,lastResort可以设置为None.

版本3.2.

与警告模块集成

captureWarnings()功能可以用来整合loggingwarningsmodule.

logging.captureWarningscapture
此功能用于通过登录和关闭来转动警告捕获.

如果captureTrue,发出的警告warnings模块将被重定向到日志系统。具体来说,使用warnings.formatwarning()格式化警告,并将生成的字符串记录到名为"py.warnings"的记录器,严重性为WARNING.

如果captureFalse,警告重定向到记录系统将停止,警告将被重定向到其原始目的地(即在调用captureWarnings(True)之前生效的那些).

参见

模块logging.config
记录模块的配置API。
模块logging.handlers
记录模块附带的有用处理程序.
PEP 282 – 记录系统
描述此功能的提议包含在Python标准库中
原始Python日志包
这是logging包的原始来源。本网站提供的软件包版本适用于Python 1.5.2,2.1.x和2.2.x,不包括标准库中的logging软件包.

评论被关闭。