Python 日志为什么会重复输出:从 handler、propagate 到可测试配置
Python 日志重复输出,很多时候不是业务代码执行了两次,而是同一个 LogRecord 经过 logger 层级中的两条输出路径。本文从 handler、propagate 和配置函数幂等性三个角度,使用 Python 标准库示例说明问题来源,并给出应用、库代码与测试环境中可以落地的排查方法。
1. 先分清 logger、handler 和 formatter
logger 负责产生和分发 LogRecord;handler 决定记录写到终端、文件还是内存流;formatter 负责把记录转换为文本。一个 logger 可以拥有多个 handler,一条记录也可能继续交给父 logger。
例如 service.api 的父 logger 是 service,再往上是根 logger。排查重复输出时,不能只看 日志调用 的调用次数,还要查看当前 logger 的 handlers、父级 handlers 和 propagate 的值。
2. 重复输出其实是两条路径
假设根 logger 有一个 handler,service.api 又有一个 handler,同时子 logger 保持默认的传播行为。记录会先由子 logger 的 handler 处理,然后继续向根 logger 传播,根 logger 的 handler 再处理一次。两条 handler 如果写入同一个目标,看起来就像日志被执行了两次。
这个判断很重要:删掉一处业务日志调用可能暂时消失,却没有修复输出拓扑。真实服务里两条路径也可能分别写控制台和文件,或者分别进入两个采集器。
3. 应用配置要有明确的输出边界
应用可以在启动入口统一创建 handler,业务模块只调用 logging.getLogger(name),不要在每个模块导入时主动创建终端 handler。这样可以避免重载、重复导入或插件初始化带来额外输出路径。
如果某个子 logger 必须独立输出,则给它配置专属 handler,并设置 propagate = False。这表示记录已在当前边界完成处理,不再交给父级。库代码则应尽量不创建 FileHandler 或 StreamHandler,可以使用 NullHandler 把输出策略交给应用。
4. 配置函数必须幂等
开发服务器重载、测试夹具和插件初始化都可能多次调用配置函数。无条件执行 addHandler 会让每次调用都增加一条路径。比起只要 handlers 非空就不再配置,更安全的做法是只识别自己创建的 handler:给它加一个内部标记,配置前查找该标记,找到就复用,找不到才创建。这样不会误删框架或调用方的其他输出目标。
5. 不要混淆级别、过滤器和传播
logger level 决定记录是否继续处理,handler level 决定某一个输出目标是否接收,filter 可以根据记录字段做更细的筛选。把 logger 调成 DEBUG,并不意味着每个 handler 都会输出 DEBUG;把子 logger 调成 WARNING,也不等于已经生成的记录不会被父级观察到。
排查时可以暂时记录 logger 名称、级别、传播开关,以及从当前 logger 到根 logger 的 handler 类型和数量。生产环境不要把令牌、Cookie 或连接字符串等敏感配置直接写入诊断日志。
6. 测试要隔离进程级 logging 状态
logger 注册表是进程级状态。测试若修改根 logger 却没有清理 handler,后续测试可能出现单独运行正常、整套运行重复。可以使用唯一 logger 名称、专用内存流,并只删除测试自己创建的 handler。验证幂等性时连续调用两次配置函数,再写出一条记录,断言自建 handler 数量和输出行数都为预期值。
7. 标准库示例
下面的示例不写真实文件,也不依赖第三方包。它先让父子 handler 写入同一个内存流,验证传播导致双输出;再关闭传播;最后连续调用配置函数,验证只保留一个由示例管理的 handler。
import io
import logging
def reset_logger(logger):
for handler in list(logger.handlers):
logger.removeHandler(handler)
handler.close()
logger.setLevel(logging.NOTSET)
logger.propagate = True
def configure_logger(name, stream):
logger = logging.getLogger(name)
logger.setLevel(logging.INFO)
logger.propagate = False
owned = next((item for item in logger.handlers if getattr(item, "_demo_owned", False)), None)
if owned is None:
owned = logging.StreamHandler(stream)
owned._demo_owned = True
owned.setFormatter(logging.Formatter("%(levelname)s:%(message)s"))
logger.addHandler(owned)
return logger
def main():
root = logging.getLogger()
child = logging.getLogger("demo.service")
reset_logger(root)
reset_logger(child)
shared = io.StringIO()
root_handler = logging.StreamHandler(shared)
root_handler.setFormatter(logging.Formatter("%(message)s"))
root.addHandler(root_handler)
child_handler = logging.StreamHandler(shared)
child_handler.setFormatter(logging.Formatter("%(message)s"))
child.addHandler(child_handler)
child.setLevel(logging.INFO)
child.info("once, but two handlers")
assert shared.getvalue().splitlines() == ["once, but two handlers"] * 2
print("PASS propagation explains duplicate output")
shared.seek(0); shared.truncate(0)
child.propagate = False
child.info("one output path")
assert shared.getvalue().splitlines() == ["one output path"]
print("PASS propagate=False leaves one output path")
reset_logger(child)
shared.seek(0); shared.truncate(0)
configured = configure_logger("demo.service", shared)
configure_logger("demo.service", shared)
configured.info("configured once")
assert sum(getattr(item, "_demo_owned", False) for item in configured.handlers) == 1
assert shared.getvalue().splitlines() == ["INFO:configured once"]
print("PASS configuration is idempotent")
reset_logger(root); reset_logger(child)
if __name__ == "__main__":
main()
8. 排查清单与结语
遇到重复日志时,可以依次确认:日志调用是否执行一次;当前 logger 和父级有哪些 handler;临时设置 propagate = False 后是否恢复单行;初始化入口是否重复添加 handler;测试捕获器和开发服务器重载器是否也在输出。不要把全局清空 handlers 当成通用修复,因为它可能删除调用方明确创建的审计或文件输出。应该明确 handler 的所有权、生命周期和最终输出边界。
日志重复不是 logging 的随机行为,而是层级、handler 与传播路径共同决定的结果。统一入口配置、库不抢占输出、独立子树关闭传播、初始化幂等,并用隔离状态的测试验证这些约束,就能让一次事件只输出一次成为可检查的设计。
- 点赞
- 收藏
- 关注作者
评论(0)