Python logging QueueHandler 如何避免业务线程被日志阻塞

如果接口线程一边处理请求，一边直接写文件、发邮件或调用远程日志服务，日志调用就可能把业务延迟一起拉高。这个问题的处理重点不是简单地把 logger 换成另一个对象，而是把慢速 handler 从业务线程移到 QueueListener 的消费线程。

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

最小可靠方案是：业务侧只挂 QueueHandler，监听侧挂真正的 FileHandler 或网络 handler；应用退出前调用 listener.stop()，让队列中已接收的记录有机会处理完。

为什么同步 FileHandler 会拖住业务线程

FileHandler.emit() 不只包含一次函数调用，它还可能等待格式化、文件系统写入或锁竞争。请求线程在这段时间里无法继续处理自己的任务。把队列加在 logger 后面，只能解决“谁来执行输出”的分工；如果监听器仍然没有独立运行，延迟并不会消失。

排查时先看业务线程的耗时分布，再看日志目标是否包含文件、SMTP、HTTP 或自定义远程 handler。若慢点确实来自输出，就把这些 handler 从业务 logger 上移走，而不是把日志级别一味调高。

把慢处理器移到 QueueListener 线程

下面的最小配置让业务 logger 只完成记录创建和入队。格式化、文件打开与写入都发生在监听线程中；respect_handler_level=True 则让监听器继续尊重真实 handler 的级别。

import logging
import logging.handlers
import queue

# 队列负责传递 LogRecord；无界队列降低入队阻塞，但要监控积压。
log_queue = queue.Queue()

# 慢速输出只放到监听器线程，不直接挂到业务 logger。
file_handler = logging.FileHandler("service.log", encoding="utf-8")
file_handler.setLevel(logging.INFO)
file_handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s %(name)s %(message)s"
))

# 监听器从队列取记录，再调用 file_handler。
listener = logging.handlers.QueueListener(
    log_queue, file_handler, respect_handler_level=True
)
queue_handler = logging.handlers.QueueHandler(log_queue)
logger = logging.getLogger("service")
logger.setLevel(logging.INFO)
logger.addHandler(queue_handler)

listener.start()
try:
    # 业务线程只把记录交给队列，不执行文件写入。
    logger.info("request accepted")
finally:
    # 退出前先停止监听器，它会等待队列中的记录处理完。
    listener.stop()
    file_handler.close()

生产代码通常把启动和停止封装到应用生命周期中，避免每个请求创建一套监听器。多个业务 logger 也可以共享一个队列和同一个 listener，这比每个输出 handler 各自创建线程更节省资源。

级别、队列满载和 prepare 的三个边界

官方实现的 prepare() 会合并消息和参数，并清理部分异常字段以便传递；如果监听侧还需要自定义异常格式，可以继承 QueueHandler 重写它。若使用有界队列，要明确“丢弃、阻塞还是降级到 stderr”的策略，因为默认入队失败可能被 handleError() 处理掉。

跨进程时不要把 multiprocessing 内部日志和同一个 multiprocessing.Queue 的 QueueHandler 混在一起，否则可能递归记录或死锁；跨进程集中写文件还应优先参考官方 Cookbook 的 listener 进程方案。

退出时为什么必须 stop

listener.stop() 会请求后台线程结束，并等待它完成。它不是可有可无的清理动作：如果进程直接退出，队列里已经接收但尚未交给真实 handler 的记录可能永远不会落盘。对于服务框架，应把它放在 shutdown hook、上下文管理器或主循环的 finally 中。

复查效果可以做两组对照：记录业务线程一次日志调用的耗时，同时观察 listener 处理时间和队列长度。业务延迟下降但队列持续增长，说明只是把瓶颈藏起来；这时需要减少日志量、拆分慢目标或提高消费能力，而不是无限放大队列。

相关问题

QueueHandler 会让日志完全不阻塞吗？

不会。队列满载、记录准备本身很重或队列出现锁竞争时仍可能失败或变慢；它主要把慢速输出从业务线程转移出去。

为什么 stop 后还要关闭 FileHandler？

stop()负责让监听线程处理完队列，关闭 handler 则负责释放文件资源。先 stop、后 close，避免监听线程还在写文件时被提前关闭。

应该用无界队列还是有界队列？

低延迟且允许短时积压可用无界队列，但必须监控内存；强约束内存时用有界队列，并把满载时的丢弃或降级策略写清楚。