Python logging用 QueueHandler 隔离日志 I/O的实现方法

当接口线程既要处理请求，又要把日志写入文件或发送到慢速 handler 时，日志调用会把 I/O 延迟带回业务路径。更稳妥的做法是让 QueueHandler 只把 LogRecord 放进队列，再由 QueueListener 在独立线程中驱动真正的输出 handler。这样隔离的是日志 I/O，不是把日志变成可靠消息队列。

官方文档：https://docs.python.org/3/library/logging.handlers.html

QueueHandler 与 QueueListener 如何分工

QueueHandler 是入口 handler，职责是把记录交给队列；QueueListener 负责从队列取记录，并把它交给一个或多个真实 handler。官方文档把两者设计为配套使用，适合把文件写入、邮件发送等可能变慢的工作移到监听线程。

这里的边界很重要：队列只负责线程间交接，真正的格式化和写入仍由 FileHandler 等对象完成。若应用突然退出，尚未消费的记录仍可能丢失，因此必须把停止监听器当作生命周期的一部分。

创建队列和监听器的最小实现

下面的示例把业务 logger 的传播关闭，避免记录又沿 root logger 输出一次；代码中的文件 handler 只是示例，换成控制台或自定义 handler 时，队列结构不变。

import logging
import queue
from logging.handlers import QueueHandler, QueueListener

# 有界队列用于限制日志积压占用的内存；容量应结合业务峰值调整
log_queue = queue.Queue(maxsize=1000)

# 真正的 I/O handler 只由监听线程使用
file_handler = logging.FileHandler("service.log", encoding="utf-8")
file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))

# 入口 handler 只负责入队，业务线程不会直接写文件
queue_handler = QueueHandler(log_queue)
logger = logging.getLogger("service")
logger.setLevel(logging.INFO)
logger.propagate = False
logger.addHandler(queue_handler)

# 监听线程从队列取 LogRecord，再交给文件 handler
listener = QueueListener(log_queue, file_handler, respect_handler_level=True)

try:
    # 先启动消费端，再进入业务逻辑，避免开头日志无人处理
    listener.start()
    logger.info("worker ready")
finally:
    # 停止前让监听器处理完队列中的记录，随后释放文件资源
    listener.stop()
    file_handler.close()

用 try/finally 管好监听器生命周期

常见坑不是不会创建队列，而是只调用 start()，忘了在异常路径和正常退出路径调用 stop()。stop() 会结束监听线程并处理收尾；如果业务还会动态增加 handler，也应在停机阶段先停止写入，再统一关闭资源。

respect_handler_level=True 时，监听器会考虑目标 handler 的级别；不设置时，记录会按旧行为交给每个目标 handler。生产配置中要把 logger 级别、QueueHandler 和目标 handler 级别分别列出来，排查“日志没有落盘”时不要只看一个 level。

容量、异常与多进程边界

如果只是单进程多线程，标准库的 queue.Queue 足够。多进程时不要直接照搬线程示例，尤其不要把 multiprocessing 内部 logger 与同一队列混用而不检查递归风险。异步队列降低的是调用线程等待时间，不能替代磁盘、远端日志服务或进程级可靠投递。

上线前的检查清单与相关问题

• 启动顺序是否为先 listener、后业务 logger？
• root logger 传播是否造成重复输出？
• 异常、信号或优雅停机路径是否会执行 stop？
• 队列满时的行为是否可观测，是否有可接受的降级策略？

QueueHandler 会让日志绝对不阻塞吗？

不会。入队、队列满时的处理和记录准备仍可能耗时；它主要把慢速输出 I/O 从业务线程移开。

为什么 stop 不能省略？

省略 stop 会让监听线程和尾部记录的处理依赖进程退出时机，优雅停机时容易留下未消费日志。

QueueListener 能替代集中式日志系统吗？

不能。它只解决当前进程内的日志交接和 handler 调度，检索、持久化和跨主机聚合仍需要其他系统。