logging QueueHandler怎么配置或排查

Python 的 logging.handlers.QueueHandler 不是“自动把日志写进文件”的开关，它只负责把 LogRecord 投递到队列；真正格式化和落盘的是后台线程里的 QueueListener 及其目标 handler。配置后出现“偶尔没有日志”，通常要先分清是没有入队、没有消费，还是程序退出前没有收尾。

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

先把 QueueHandler 链路接通：一个可收尾的异步日志小项目

小项目只保留一条清晰链路：业务 logger 产生记录，QueueHandler 负责投递，queue.Queue 暂存，QueueListener 在独立线程中消费，最后交给 RotatingFileHandler。这样既不会让业务线程直接承担文件 I/O，也不会把“队列”误认为最终存储。

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

def build_logging():
    # 有界队列让容量成为明确的排查边界。
    log_queue = queue.Queue(maxsize=1000)
    root = logging.getLogger()
    root.setLevel(logging.INFO)

    # 目标 handler 只在监听线程中写文件。
    file_handler = RotatingFileHandler(
        "app.log", maxBytes=10 * 1024 * 1024,
        backupCount=3, encoding="utf-8"
    )
    file_handler.setLevel(logging.INFO)
    file_handler.setFormatter(logging.Formatter(
        "%(asctime)s %(levelname)s %(name)s %(message)s"
    ))

    # 业务线程只把记录交给队列，不直接触碰文件。
    queue_handler = QueueHandler(log_queue)
    root.addHandler(queue_handler)

    # 监听线程负责取记录并调用目标 handler。
    listener = QueueListener(
        log_queue, file_handler, respect_handler_level=True
    )
    listener.start()
    return listener

listener = build_logging()
try:
    # 这里代表业务代码；服务中只初始化一次 logger 链路。
    logging.getLogger("worker").info("worker ready")
finally:
    # 退出前等待队列中的记录交给目标 handler。
    listener.stop()

这里的 listener.stop() 是生命周期的一部分，不是可有可无的清理语句。长驻服务应在进程关闭钩子或应用 shutdown 阶段调用它；不要在每个请求结束时反复创建和停止 listener。

QueueHandler 看似配置成功却丢日志，先查这四个边界

第一，看队列是否有容量限制。QueueHandler 默认通过 put_nowait() 入队，队列满时会走 handleError()；如果 logging.raiseExceptions 关闭，记录可能安静地丢掉。第二，看 listener 是否真正启动，以及目标 handler 是否被传入。第三，看应用是否在日志刚入队后立即退出，未调用 stop() 就可能留下尾部记录。第四，检查是否把需要跨进程共享的队列和单进程线程模型混用了。

QueueHandler.prepare() 还会把消息和参数合并，并清理部分异常信息以便排队或序列化。因此如果监听端还需要原始 exc_info 或自定义结构，应明确覆写 prepare()，不要只在 formatter 上反复试参数。

把配置改成可排查的检查清单

验收时按“投递—消费—目标 handler—收尾”四段记录证据：先确认 logger 确实挂了 QueueHandler；再确认 listener 已启动且队列类型匹配；随后检查目标 handler 的级别、文件路径和 formatter；最后在停止阶段调用 stop()。如果使用有界队列，至少要决定满载时是允许丢弃、阻塞等待，还是把告警转到独立的应急通道。这个选择比简单把 maxsize 调大更重要。

对于 multiprocessing，官方文档特别提醒不要使用 SimpleQueue，并避免让 multiprocessing 的内部 logger 与 QueueHandler 共用同一个 multiprocessing.Queue，否则可能递归记录甚至死锁。线程异步和进程间传输是两个问题，先选对模型，再谈参数。

常见问题

QueueHandler 一定比直接写文件更快吗？

它通常能把文件 I/O 从产生日志的线程移开，但队列满、listener 停止或目标 handler 变慢时，优势会变成排队压力；不能把它当成无损和无限容量的保证。

为什么设置了 formatter，监听端仍看不到异常堆栈？

基础 prepare() 会合并消息并清理 exc_info、exc_text 等字段。需要保留原始异常上下文时，应自定义 prepare 逻辑并确认对象可安全排队。

只调用 listener.start() 不调用 stop() 可以吗？

短命脚本可能“看起来能工作”，但退出时队列仍可能有未处理记录。服务应在关闭流程中显式 stop，给监听线程完成消费的机会。