Python logging QueueHandler 怎么把日志写入后台线程

如果日志格式化、文件写入或网络输出会拖慢业务线程，可以把真正的输出 handler 放到 QueueListener 的后台线程。做法不是只创建一个 QueueHandler，而是把三件事连起来：业务 logger 把 LogRecord 放入 queue.Queue，监听器线程从队列取出记录，再交给 StreamHandler 或 FileHandler。退出前还要显式调用 listener.stop()，否则队列里尚未处理的记录可能来不及写出。

最小可靠结构是“业务 logger + QueueHandler + queue.Queue + QueueListener + 真实输出 handler”。QueueHandler 负责入队，QueueListener 负责消费；不要把两者混成一个 handler，也不要用进程结束代替 stop。

QueueHandler 和 QueueListener 各自负责什么

QueueHandler 是业务侧的轻量入口。它会准备一条记录并放入队列；默认的 prepare() 会把消息和参数合并，还会清理部分异常信息以便记录可被安全传递。QueueListener 则在自己的线程中读取队列，并把记录交给一个或多个真正的 handler。

用 QueueListener 把输出移到后台线程

下面的例子使用标准库控制台 handler。注意 logger 只挂一个 QueueHandler，输出格式交给监听器侧的 StreamHandler；这样业务线程不会重复格式化同一条消息。

import logging
import logging.handlers
import queue
import sys

# 队列只承载 LogRecord，真正的输出放在监听器线程
log_queue = queue.Queue()
console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))

# 监听器线程从队列取记录，再调用 console.emit()
listener = logging.handlers.QueueListener(
    log_queue,
    console,
    respect_handler_level=True,
)

logger = logging.getLogger("worker")
logger.setLevel(logging.INFO)
logger.propagate = False
queue_handler = logging.handlers.QueueHandler(log_queue)
logger.addHandler(queue_handler)
listener.start()

try:
    # 业务线程只负责创建并提交日志记录
    for item_id in range(3):
        logger.info("处理任务 item_id=%s", item_id)
finally:
    # 不再接收新记录，再等待监听器处理完队列中的记录
    logger.removeHandler(queue_handler)
    listener.stop()
    console.close()

在这段代码中，logger.info() 返回得很快，但不代表输出已经完成；它只代表记录已经交给 QueueHandler。listener.stop() 会向监听器发出停止信号并等待线程结束，因此必须放在输出 handler 关闭之前。

有界队列、异常信息和退出刷新怎么处理

生产环境常会给队列设置 maxsize，防止日志高峰无限占用内存。但 QueueHandler.enqueue() 默认使用非阻塞 put_nowait()；队列已满时，记录会交给 handleError()，在关闭异常输出的配置下可能被静默丢弃。你必须先决定日志是“不能阻塞业务”还是“不能丢失”：前者保留默认策略并监控丢弃，后者可以覆写 enqueue() 使用带超时的阻塞入队。

异常日志也要留意 prepare() 的边界。默认实现会把消息参数合并，并清理 exc_info 等字段；如果监听器侧还需要自定义异常格式，可以继承 QueueHandler 保存一份可序列化的异常文本，而不是直接假设原始参数仍然存在。

常见问题

只创建 QueueHandler，不创建 QueueListener 可以吗？

不行。这样记录只会进入队列，没有消费者，最终既不会写入控制台，也不会写入文件。除非你自己实现等价的消费线程，否则必须把 QueueListener 或自定义消费者接上。

调用 logging.shutdown() 就能保证队列排空吗？

不能把它当成 QueueListener.stop() 的替代品。logging.shutdown() 负责通知 logging 系统刷新并关闭 handler；队列监听线程的生命周期仍应由 listener.stop() 管理。应用退出路径中先停止监听器，再关闭输出资源，边界最清楚。

官方接口说明可参考 logging.handlers 与 logging 文档。