KBEngine 内嵌 Python 标准库 logging 模块全解析:从 Logger/Handler/Formatter 三大组件到模块级 API 的完整参考
KBEngine 内嵌 Python 标准库 logging 模块全解析:从 Logger/Handler/Formatter 三大组件到模块级 API 的完整参考
导读
本文以 KBEngine 仓库内嵌 Python 发行版中的官方文档 kbe/src/lib/python/Doc/library/logging.rst 为主体,系统讲解 Python 标准库 logging 模块的完整 API:从应用代码直接使用的 Logger、决定日志去向的 Handler、精细化过滤的 Filter,到控制最终输出布局的 Formatter,再到 LogRecord 的完整属性字典与全部模块级函数。对于在 KBEngine 的 Python 服务端脚本、工具脚本(如 webconsole 中的 Django 组件)中接入日志系统、排查多进程多线程服务日志、自定义日志级别与格式化输出的开发者,读完本文即可掌握 logging 模块全部核心对象的用法、参数含义与源码级行为细节。
模块概览:四大核心组件与模块的价值
logging 模块定义了一套灵活的事件日志系统,供应用程序和库共同使用。它最核心的价值在于:日志 API 来自标准库,因此所有 Python 模块都能参与日志记录——你的应用日志可以把自己的消息与第三方模块产生的消息整合在同一个日志流中,无需第三方库关心你的日志基础设施。
模块定义的基础类及其职能如下:
| 组件 | 职责 |
|---|---|
| Loggers(记录器) | 暴露应用代码直接使用的接口,负责接收日志调用 |
| Handlers(处理器) | 把 Logger 产生的日志记录(LogRecord)发送到合适的去向(文件、终端、网络、邮件等) |
| Filters(过滤器) | 提供比级别更细粒度的机制,决定哪些日志记录应当输出 |
| Formatters(格式化器) | 规定日志记录在最终输出中的布局 |
在 KBEngine 仓库内嵌的 Python 中,该模块的源码位于 kbe/src/lib/python/Lib/logging/init.py(核心实现)、kbe/src/lib/python/Lib/logging/handlers.py(标准处理器)与 kbe/src/lib/python/Lib/logging/config.py(配置 API)。下文所有类与方法的行为描述均可直接对照 init.py 中的实现验证。
Logger 对象:应用代码直接使用的接口
Logger 从来不会被直接实例化,而是始终通过模块级函数 logging.getLogger(name) 获取。对同一个 name 多次调用 getLogger 返回的是同一个 Logger 对象的引用,因此 Logger 实例不需要在应用各部分之间传递。
Logger 名称层级(Hierarchy)
name 是潜在的以句点分隔的层级值,如 foo.bar.baz(也可以只是 foo)。层级列表中更靠下的 Logger 是更靠上层 Logger 的子级:给定名为 foo 的 Logger,则 foo.bar、foo.bar.baz、foo.bam 都是 foo 的后代。Logger 名称层级与 Python 包层级类似,如果按模块组织 Logger(推荐写法 logging.getLogger(__name__)),两者就完全一致——因为在模块中 __name__ 就是该模块在 Python 包命名空间中的名字。
Logger.propagate(传播开关)
- 若该属性为真(构造时默认为
True),记录到该 Logger 的事件除了交给自身挂载的 handler 外,还会传给更高级别(祖先)Logger 的 handler。消息直接传给祖先 Logger 的 handler——祖先 Logger 自身的级别与过滤器不会被考虑。 - 若为假,日志消息不会传给祖先 Logger 的 handler。
一个常见陷阱是:如果你同时给某个 Logger 和它的一个或多个祖先挂载 handler,同一条记录可能被多次输出。一般而言不应给超过一个 Logger 挂 handler——只需挂到层级中合适的最上层 Logger 上,只要后代 Logger 的 propagate 保持 True,它就能看到所有后代记录的事件。最常见的做法是只给 root logger 挂 handler,其余交给传播机制处理。
Logger.setLevel(level)
为该 Logger 设置阈值:严重程度低于 level 的消息被忽略,达到或高于 level 的消息交给服务该 Logger 的 handler 输出(除非某个 handler 自身级别设得更高)。
创建 Logger 时级别为 NOTSET(对 root logger 意味着所有消息都被处理;对非 root Logger 意味着委托给父级)。注意 root logger 创建时的级别是 WARNING。
"委托给父级(delegation to the parent)"的含义是:如果一个 Logger 级别为 NOTSET,会沿其祖先链向上遍历,直到找到一个级别非 NOTSET 的祖先,或到达 root。找到非 NOTSET 的祖先,则该祖先的级别被当作起点 Logger 的有效级别来决定事件如何处理;若到达 root 且其级别为 NOTSET,则所有消息都被处理,否则使用 root 的级别作为有效级别。
从 3.2 起,level 参数除了整数常量(如 INFO)外,也接受字符串表示(如 'INFO')。但级别内部仍以整数存储,像 getEffectiveLevel、isEnabledFor 等方法仍返回/期望整数。
Logger.isEnabledFor(lvl) 与 getEffectiveLevel()
isEnabledFor(lvl):判断严重程度 lvl 的消息是否会被该 Logger 处理。该方法先检查模块级logging.disable(lvl)设置的级别,再检查由getEffectiveLevel得到的有效级别。getEffectiveLevel():返回有效级别。若已通过setLevel设置了非 NOTSET 的值,直接返回该值;否则沿层级向 root 遍历,直到找到非 NOTSET 的值并返回。返回值是整数,通常为logging.DEBUG、logging.INFO等。
Logger.getChild(suffix)
返回当前 Logger 的后代 Logger,由 suffix 决定。因此 logging.getLogger('abc').getChild('def.ghi') 与 logging.getLogger('abc.def.ghi') 返回同一个 Logger。这是一个便捷方法,当父 Logger 用 __name__ 命名时非常有用(3.2 新增)。
日志调用方法:debug / info / warning / error / critical / log / exception
Logger.debug(msg, *args, **kwargs) 以 DEBUG 级别记录消息:msg 是消息格式字符串,args 通过字符串格式化运算符合并进 msg(因此也可以在格式字符串中使用关键字,配合单个字典参数)。
debug 会检查三个关键字参数:
- exc_info:若非假值,异常信息会被加入日志消息。如果提供了异常元组(
sys.exc_info返回的格式)或异常实例,则使用之;否则调用sys.exc_info()获取。从 3.5 起该参数还可接受异常实例。 - stack_info:默认为
False。若为真,栈信息会被加入日志消息,包含实际的日志调用点。注意它和 exc_info 显示的栈不同:前者是从栈底到当前线程中日志调用点的栈帧;后者是异常发生后在搜索异常处理器过程中已展开的栈帧信息。stack_info 可独立于 exc_info 使用(例如即使没有异常,也想展示如何到达代码中某处)。栈帧打印在标题行Stack (most recent call last):之后,模仿异常栈的Traceback (most recent call last):(3.2 新增)。 - extra:可传入一个字典,用来给本次日志事件创建的 LogRecord 的
__dict__填充用户自定义属性,这些自定义属性之后可被任意使用(例如并入日志消息)。
extra 的典型用法(文档原例):
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 的格式字符串期望 LogRecord 属性字典里有 clientip 和 user,若缺失,字符串格式化会抛异常导致消息无法记录,因此必须始终传入包含这些键的 extra 字典。该特性正是为多线程服务器这类特殊场景设计的——同一份代码在多上下文中执行,而值得关注的条件依赖于上下文(如远端客户端 IP、已认证用户名)。
其余方法参数与 debug 完全一致:
info(msg, *args, **kwargs):INFO 级别。warning(msg, *args, **kwargs):WARNING 级别。注意存在功能相同的废弃方法warn,应使用warning。error(msg, *args, **kwargs):ERROR 级别。critical(msg, *args, **kwargs):CRITICAL 级别。log(lvl, msg, *args, **kwargs):以整数级别 lvl 记录。exception(msg, *args, **kwargs):以 ERROR 级别记录,并附加异常信息,只能在异常处理器中调用。
过滤器相关:addFilter / removeFilter / filter
addFilter(filter):给该 Logger 添加过滤器。removeFilter(filter):移除过滤器。filter(record):对该记录应用 Logger 的过滤器,若记录应被处理则返回真值。过滤器被依次咨询,直到某个返回假值——此时不再进一步处理该记录(不传给 handler);若没有过滤器返回假值,记录将被处理。
Handler 管理:addHandler / removeHandler / handle / hasHandlers
addHandler(hdlr)、removeHandler(hdlr):添加/移除 handler。findCaller(stack_info=False):查找调用者的源文件名与行号,返回 (filename, lineno, function name, stack info) 四元组;除非 stack_info 为真,否则栈信息为None。handle(record):把记录传给该 Logger 及其祖先关联的所有 handler(直到遇到 propagate 为假值为止)。该方法既用于从 socket 收到的反序列化(unpickled)记录,也用于本地创建的记录。Logger 级过滤通过filter应用。makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None):工厂方法,可在子类中覆写以创建特化的LogRecord实例。hasHandlers():检查该 Logger 是否配置了任何 handler——在 Logger 自身及其父级中查找(3.2 新增)。只要遇到propagate为假的 Logger 就停止向上搜索,该 Logger 是检查存在性的最后一个。
从 3.7 起,Logger 可以被 pickle 和 unpickle。
日志级别(Logging Levels)
级别的数值如下表。若你自定义级别并需要它们与预定义级别保持特定数值关系,这张表最关键;若自定义级别与预定义级别数值相同,会覆盖预定义值并丢失其预定义名称。
| Level | Numeric value |
|---|---|
CRITICAL |
50 |
ERROR |
40 |
WARNING |
30 |
INFO |
20 |
DEBUG |
10 |
NOTSET |
0 |
Handler 对象:日志记录的去向
Handler 永远不会被直接实例化,它是更有用子类的基类。但子类的 __init__ 必须调用 Handler.__init__。
核心方法
__init__(level=NOTSET):通过设置级别、把过滤器列表置空、用createLock创建锁(用于串行化对 I/O 机制的访问)来初始化实例。createLock()/acquire()/release():创建线程锁并获取/释放之,用于串行化访问可能非线程安全的底层 I/O。setLevel(level):设置 handler 的阈值,低于 level 的消息被忽略。handler 创建时级别为 NOTSET(处理所有消息)。从 3.2 起同样接受字符串级别。setFormatter(fmt):为该 handler 设置Formatter。addFilter(filter)/removeFilter(filter):添加/移除过滤器。filter(record):依次咨询 handler 的过滤器,直到某个返回假值——此时 handler 不输出该记录;全部通过则输出。flush():确保所有日志输出已刷新。基类实现什么都不做,由子类实现。close():清理 handler 使用的资源。基类实现不输出但会把自己从内部 handler 列表中移除(shutdown调用时会关闭该列表),覆写close的子类应确保调用它。handle(record):根据 handler 上可能挂载的过滤器,有条件地输出记录;以获取/释放 I/O 线程锁的方式包装实际输出。handleError(record):当emit期间遇到异常时由 handler 调用。若模块级属性raiseExceptions为False,异常被静默忽略——这通常是日志系统想要的(多数用户不关心日志系统自身的错误,更关心应用错误)。当然你也可以换成自定义 handler。默认raiseExceptions为True,开发期更有用。format(record):对记录做格式化——若设置了 formatter 则使用它,否则使用模块默认 formatter。emit(record):实际输出日志记录。基类实现抛出NotImplementedError,由子类实现。
标准库随附的 handler 列表见 kbe/src/lib/python/Lib/logging/handlers.py,包括 RotatingFileHandler(按大小滚动)、TimedRotatingFileHandler(按时间滚动)、SocketHandler、DatagramHandler、SysLogHandler、SMTPHandler、HTTPHandler、MemoryHandler、QueueHandler 等,详见 logging.handlers 模块文档。
Formatter 对象:控制输出布局
Formatter 负责把 LogRecord 转换成(通常是)字符串,供人或外部系统解读。基类允许指定格式字符串;若不指定,默认值为 '%(message)s'(只包含日志调用中的消息)。要在格式化输出中加入更多信息(如时间戳),请继续阅读。
Formatter 可用格式字符串初始化,它利用对 LogRecord 属性的了解——默认值正是利用"用户消息与参数已被预格式化为 LogRecord 的 message 属性"这一事实。格式字符串使用标准 Python %-风格映射键。所有有用的 LogRecord 映射键见下文"LogRecord attributes"一节。
Formatter(fmt=None, datefmt=None, style='%')
- fmt:整体消息格式字符串,不指定则用
'%(message)s'。 - datefmt:消息中日期/时间部分的格式字符串,不指定则使用
formatTime文档中描述的格式。 - style:可为
'%'、'{'或'$',决定格式字符串如何与数据合并——分别对应 %-格式化、str.format和string.Template(3.2 新增)。
format(record)
以记录的属性字典作为字符串格式化操作的运算对象,返回结果字符串。格式化前有几项准备工作:
- 用
msg % args计算记录的 message 属性; - 若格式字符串含
'%(asctime)s',调用formatTime格式化事件时间; - 若有异常信息,用
formatException格式化并追加到消息后。注意格式化后的异常信息会缓存在 exc_text 属性中——这对"异常信息可被 pickle 并经网络传输"有用;但若存在多个自定义异常格式化的 Formatter 子类,需要在一个 Formatter 完成格式化后清掉缓存值,以免下一个处理该事件的 Formatter 使用缓存而非重新计算。 - 若有栈信息,在异常信息之后追加,必要时用
formatStack转换。
formatTime(record, datefmt=None)
供想要使用格式化时间的 formatter 从 format 调用。可被覆写以满足特定需求,但基本行为是:若指定 datefmt(字符串),则用 time.strftime 格式化记录的创建时间;否则使用格式 '%Y-%m-%d %H:%M:%S,uuu'(uuu 为毫秒值,其余字母含义见 time.strftime 文档),示例时间如 2003-01-23 00:29:50,411。
该方法使用用户可配置的函数把创建时间转换为元组:默认用 time.localtime;要改变某个 formatter 实例的转换,可把实例的 converter 属性设为与 time.localtime 或 time.gmtime 签名相同的函数;要让所有 formatter 都改(例如全部以 GMT 显示),则设置 Formatter 类的 converter 属性。
从 3.3 起,默认的时间格式不再硬编码,而是定义为可覆写的类级属性:default_time_format(strptime 格式串)与 default_msec_format(追加毫秒值)。
formatException(exc_info) 与 formatStack(stack_info)
formatException(exc_info):把异常信息(sys.exc_info返回的标准异常元组)格式化为字符串。默认实现直接用traceback.print_exception。formatStack(stack_info):把栈信息(traceback.print_stack返回的字符串,去掉末尾换行)格式化为字符串。默认实现直接返回输入值。
Filter 对象:比级别更细粒度的过滤
Filter 可被 Handler 和 Logger 用于比级别更精细的过滤。基类过滤器只允许 Logger 层级中某个节点之下的那些事件:例如用 'A.B' 初始化的过滤器,允许 Logger 'A.B'、'A.B.C'、'A.B.C.D'、'A.B.D' 等记录的事件,但不允许 'A.BB'、'B.A.B' 等。用空字符串初始化则放行所有事件。
Filter(name=''):返回Filter实例。若指定 name,它命名一个 Logger,该 Logger 及其子级的事件将通过过滤器;name 为空串则放行所有事件。filter(record):判断指定记录是否应被记录。返回 0 表示否,非 0 表示是。必要时该方法可原地修改记录。
注意挂载位置的区别:挂在 handler 上的过滤器在事件被 handler 输出前咨询;挂在 logger 上的过滤器在事件被记录时(使用 debug、info 等时)、发送给 handler 之前咨询。这意味着由后代 Logger 产生的事件不会被某个 Logger 的过滤器过滤,除非该过滤器也应用到了那些后代 Logger。
你其实不需要子类化 Filter:任何具有相同语义 filter 方法的实例都可以直接传入。从 3.2 起更宽松:可以直接传函数(或任何可调用对象)作为过滤器——过滤逻辑会检查过滤器对象是否有 filter 属性,有则按 Filter 调用其 filter 方法,否则视为可调用对象并以 record 为唯一参数调用,返回值语义同 Filter.filter。
尽管过滤器主要用于比级别更精细的条件过滤,它们能看见挂载到的 handler 或 logger 处理的每一条记录——这可用于统计某 logger/handler 处理了多少记录,或对正在处理的 LogRecord 增删改属性(需要谨慎),从而把上下文信息注入日志。
LogRecord 对象与 LogRecord attributes
LogRecord 实例由 Logger 在每次记录日志时自动创建,也可通过 makeLogRecord 手动创建(例如从网络上收到的被 pickle 的事件)。
LogRecord 构造参数
LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None) 包含与被记录事件相关的全部信息:
| 参数 | 含义 |
|---|---|
name |
记录该事件的 Logger 名称。注意即使事件可能由挂载在不同(祖先)Logger 上的 handler 输出,该名称也始终保持原值 |
level |
事件数值级别(DEBUG、INFO 等之一)。它被转换为 LogRecord 的两个属性: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 attributes 完整表(% 风格格式化)
下表按字母序列出 LogRecord 属性、含义及 %-风格格式串中的占位符。使用 {}-格式化(str.format)时占位符写作 {attrname};使用 {attrname}。{}-格式化还支持在属性名后用冒号指定格式标志,如 {msecs:03d}会把毫秒值 4 格式化为004`。
| 属性名 | 格式 | 说明 |
|---|---|---|
| args | 无需自行格式化 | 合并进 msg 以生成 message 的参数元组;当只有一个参数且为字典时,为值被用于合并的字典 |
| asctime | %(asctime)s |
LogRecord 创建时的人类可读时间,默认形如 '2003-07-08 16:49:45,896'(逗号后为毫秒部分) |
| created | %(created)f |
LogRecord 创建时间(time.time() 的返回值) |
| exc_info | 无需自行格式化 | 异常元组(sys.exc_info 风格),无异常时为 None |
| filename | %(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 | %(message)s |
被记录的已合并消息,由 msg % args 计算,在 Formatter.format 被调用时设置 |
| module | %(module)s |
模块名(filename 的名称部分) |
| msecs | %(msecs)d |
LogRecord 创建时间的毫秒部分 |
| msg | 无需自行格式化 | 原始日志调用传入的格式字符串,与 args 合并产生 message,或为任意对象 |
| name | %(name)s |
记录该调用的 Logger 名称 |
| pathname | %(pathname)s |
日志调用所在源文件的完整路径(若可用) |
| process | %(process)d |
进程 ID(若可用) |
| processName | %(processName)s |
进程名(若可用)(3.1 新增) |
| relativeCreated | %(relativeCreated)d |
LogRecord 创建时刻相对 logging 模块加载时刻的毫秒数 |
| stack_info | 无需自行格式化 | 从当前线程栈底到产生该记录的日志调用栈帧(含)的栈帧信息(若可用) |
| thread | %(thread)d |
线程 ID(若可用) |
| threadName | %(threadName)s |
线程名(若可用) |
对应源码实现可见 Lib/logging/init.py 中 LogRecord.__init__ 对 name、msg、args、levelname、levelno、pathname、filename、module、exc_info、lineno、funcName、created、msecs、relativeCreated 等属性的实际赋值;Formatter 的文档注释(init.py)也逐条列出了这些属性占位符。
LoggerAdapter:便捷传递上下文信息
LoggerAdapter 实例用于方便地把上下文信息传入日志调用。
LoggerAdapter(logger, extra):返回用底层Logger实例和类字典对象初始化的LoggerAdapter。process(msg, kwargs):修改传入日志调用的消息和/或关键字参数以插入上下文信息。默认实现把构造时传入的 extra 对象以键'extra'加入 kwargs,返回(msg, kwargs)元组。
此外,LoggerAdapter 支持以下 Logger 方法:debug、info、warning、error、exception、critical、log、isEnabledFor、getEffectiveLevel、setLevel、hasHandlers。这些方法与 Logger 中对应方法签名相同,因此两种实例可互换使用(其中 isEnabledFor、getEffectiveLevel、setLevel、hasHandlers 为 3.2 新增,均委托给底层 logger)。
线程安全
logging 模块设计为无需客户端做任何特殊处理即可线程安全:它通过 threading 锁实现——有一把锁串行化对模块共享数据的访问,每个 handler 还创建一把锁串行化对底层 I/O 的访问。
需要留意:如果使用 signal 模块实现异步信号处理器,可能无法在信号处理器内部使用 logging——因为 threading 模块的锁实现不总是可重入的,不能从这类信号处理器中调用。
模块级函数(Module-Level Functions)
除上述类外,模块还有若干模块级函数。
getLogger(name=None)
返回指定名称的 Logger;若 name 为 None,返回层级中的 root logger。指定名称时通常为点分隔的层级名,如 'a'、'a.b'、'a.b.c.d',命名完全由开发者决定。对给定名称的所有调用返回同一个 Logger 实例,因此 Logger 实例永远不需要在应用各部分间传递。
getLoggerClass() / setLoggerClass(klass)
getLoggerClass():返回标准Logger类,或最近一次setLoggerClass传入的类。可在新类定义中调用它,以确保安装自定义Logger类不会撤销其他代码已做的定制:
class MyLogger(logging.getLoggerClass()):
# ... override behaviour here
setLoggerClass(klass):告诉日志系统在实例化 logger 时使用 klass。该类应定义__init__使其只需 name 参数,且__init__应调用Logger.__init__。通常在应用实例化任何 logger 之前调用。
getLogRecordFactory() / setLogRecordFactory(factory)
getLogRecordFactory():返回用于创建LogRecord的可调用对象。setLogRecordFactory(factory):设置创建 log record 的可调用对象。工厂签名如下:
factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)
其中 name 为 logger 名;level 为数值级别;fn 为日志调用所在文件完整路径;lno 为行号;msg 为消息;args 为消息参数;exc_info 为异常元组或 None;func 为发起日志调用的函数/方法名;sinfo 为栈回溯文本(如 traceback.print_stack 提供);kwargs 为附加关键字参数。两者均为 3.2 新增,用于让开发者对日志事件对应 LogRecord 的构建拥有更多控制。
便捷记录函数:debug / info / warning / error / critical / exception / log
这些函数以对应级别在 root logger 上记录消息,参数解释与 Logger.debug 相同:
debug(msg, *args, **kwargs):DEBUG 级别,同样支持 exc_info、stack_info、extra 三个关键字参数(用法与 Logger 方法一致,含extra示例与注意事项)。info、warning、error、critical:分别对应各级别。注意存在废弃函数warn,功能与warning相同,请使用warning。exception(msg, *args, **kwargs):ERROR 级别并附加异常信息,只能在异常处理器中调用。log(level, msg, *args, **kwargs):以 level 级别记录。
重要提醒:上述便捷函数委托给 root logger,会调用 basicConfig 以确保至少有一个 handler 可用。因此在 Python 2.7.1/3.2 之前的版本中,除非在启动线程前已给 root logger 添加至少一个 handler,否则不应在线程中使用它们——早期版本 basicConfig 的线程安全缺陷(罕见情况下)会导致 handler 被多次添加到 root logger,进而同一事件输出多条消息。
disable(lvl=CRITICAL)
为所有 logger 提供覆盖级别的 lvl,优先于 logger 自身级别。需要临时压制整个应用日志输出时很有用:它禁用所有严重程度 lvl 及以下的日志调用——例如以 INFO 调用则丢弃所有 INFO 和 DEBUG 事件,WARNING 及以上按各 logger 有效级别处理。调用 logging.disable(logging.NOTSET) 可移除该覆盖级别,日志输出重新取决于各 logger 的有效级别。
注意:若定义了高于 CRITICAL 的自定义级别(不推荐),无法依赖默认参数值,必须显式传入合适的值。从 3.7 起 lvl 默认值为 CRITICAL。
addLevelName(lvl, levelName) / getLevelName(lvl)
addLevelName(lvl, levelName):在内部字典中把级别 lvl 与文本 levelName 关联,该字典用于把数值级别映射为文本表示(例如 Formatter 格式化消息时)。该函数也可用于定义自定义级别,唯一约束是:所有使用的级别必须用本函数注册、级别应为正整数、且应按严重程度递增排列。若想自定义级别,请参考自定义级别一节(custom-levels)。getLevelName(lvl):返回级别 lvl 的文本表示。预定义级别(CRITICAL、ERROR、WARNING、INFO、DEBUG)返回对应字符串;用addLevelName关联过的返回所关联名称;传入已定义级别的数值返回其字符串表示;否则返回'Level %s' % lvl。级别内部是整数(比较逻辑需要),本函数用于在整数级别与%(levelname)s格式化输出之间转换。
makeLogRecord(attrdict)
创建并返回新的 LogRecord 实例,其属性由 attrdict 定义。该函数对"接收端从 socket 收到被 pickle 的 LogRecord 属性字典并还原为 LogRecord 实例"非常有用。
basicConfig(**kwargs)
为日志系统做基础配置:创建带默认 Formatter 的 StreamHandler 并添加到 root logger。debug、info、warning、error、critical 在 root logger 没有定义任何 handler 时都会自动调用它。若 root logger 已配置了 handler,本函数不做任何事。它应在其他线程启动前由主线程调用(早期版本多线程调用可能罕见地重复添加 handler,导致消息重复)。
支持的参数:
| 参数 | 说明 |
|---|---|
filename |
指定用该文件名创建 FileHandler,而不是 StreamHandler |
filemode |
若指定 filename,以该模式打开文件,默认为 'a' |
format |
为 handler 使用指定的格式字符串 |
datefmt |
使用指定的日期/时间格式,按 time.strftime 接受 |
style |
若指定 format,为其使用该风格:'%'、'{' 或 '$'(对应 %-格式化、str.format、string.Template),默认为 '%' |
level |
把 root logger 级别设为指定级别 |
stream |
用指定流初始化 StreamHandler。与 filename 不兼容——两者同时出现会抛 ValueError |
handlers |
若指定,应为已创建 handler 的可迭代对象,添加到 root logger。未设置 formatter 的 handler 会被赋予本函数创建的默认 formatter。与 filename 或 stream 不兼容——同时出现抛 ValueError |
style 参数 3.2 新增;handlers 参数与参数兼容性检查 3.3 新增。在 Lib/logging/init.py 的 basicConfig 源码 docstring 中可看到相同参数语义的实现说明。
shutdown()
通知日志系统执行有序关闭:刷新并关闭所有 handler。应在应用退出时调用,且此调用后不应再使用日志系统。
lastResort 模块级属性
通过该属性可得到一个"最后的处理器"(last resort):一个写入 sys.stderr、级别为 WARNING 的 StreamHandler,用于在没有任何日志配置时处理日志事件——最终效果只是把消息打印到 sys.stderr,取代早期"找不到 XYZ logger 的 handler(no handlers could be found for logger XYZ)"的报错。若出于某种原因需要旧行为,可把 lastResort 设为 None。3.2 新增。在 init.py 中可见 lastResort = _defaultLastResort,其中 _defaultLastResort 是写 sys.stderr、级别为 WARNING 的 _StderrHandler;init.py 中记录了当某个 logger 没有任何 handler 时,若记录级别不低于 lastResort.level 则由 lastResort.handle(record) 兜底处理的逻辑。
与 warnings 模块的集成
captureWarnings(capture) 用于开启/关闭 logging 对 warnings 模块的捕获:
- capture 为
True时,warnings模块发出的警告被重定向到日志系统:警告用warnings.formatwarning格式化,结果以 WARNING 严重程度记录到名为'py.warnings'的 logger。 - capture 为
False时停止重定向,警告回到其原始去向(即captureWarnings(True)之前的生效状态)。
相关模块与在 KBEngine 中的落地
logging.config:logging 模块的配置 API(kbe/src/lib/python/Lib/logging/config.py),支持 dictConfig/fileConfig 等编程式或文件式配置。logging.handlers:logging 模块随附的有用处理器(kbe/src/lib/python/Lib/logging/handlers.py)。- PEP 282 - A Logging System:该特性被纳入 Python 标准库的提案。
在 KBEngine 仓库内,这一内嵌标准库模块已被项目自身的 Python 工具代码实际使用,例如 webconsole 的 Django 组件中 dwebsocket/factory.py、dwebsocket/middleware.py 等均以 import logging 接入日志系统——这正是"标准库日志 API 让各模块都能参与统一日志流"这一设计价值在项目中的直接体现。
实践要点小结
- 命名规范:模块级 Logger 用
logging.getLogger(__name__),天然形成与包层级一致的 Logger 层级。 - handler 挂载:优先只给层级顶端(通常是 root)挂 handler,依赖 propagate 传播,避免重复输出。
- 级别语义:Logger 与 Handler 各自有阈值,最终输出取两者共同约束;有效级别沿祖先链解析(init.py 的
getEffectiveLevel实现)。 - 上下文注入:单值上下文用
extra(注意与 LogRecord 标准键不冲突);需要系统性注入时用LoggerAdapter或自定义LogRecord工厂。 - 线程安全:模块默认线程安全,但
basicConfig及便捷函数应在多线程启动前于主线程完成配置。 - 兜底输出:未配置任何 handler 时,
lastResort(写 stderr、WARNING 级)保证消息不会静默丢失,便于快速定位"日志去哪了"的问题。
通过本文,读者即可在 KBEngine 的 Python 脚本与工具链中熟练运用 logging 模块:既能用 basicConfig 快速起步,也能基于 Logger/Handler/Formatter/Filter/LogRecord 构建多进程多线程服务所需的精细日志体系,并能在需要时对照仓库内嵌源码(Lib/logging/init.py)验证每一个 API 的底层行为。