QueueHandler 怎样把日志交给后台

想把日志“交给后台”，核心不是让每个日志调用自己创建线程，而是把生产和输出拆开：QueueHandler 接收日志记录并放入队列，QueueListener 在独立线程中取出记录，再交给 StreamHandler、FileHandler 等真正负责输出的 handler。这样业务线程只承担入队成本，慢速格式化、写文件或发送外部通知由监听线程处理。

官方地址：https://docs.python.org/3/library/logging.handlers.html

最小可用关系是“业务 logger → QueueHandler → queue.Queue → QueueListener → 实际 handler”。QueueHandler 不是后台线程，QueueListener 也不是日志生产者；只有把两者和队列接起来，日志才会沿着后台管线流动。

先划清 QueueHandler 和 QueueListener 的职责

QueueHandler 位于产生日志的一侧，它的队列可以来自 queue 或 multiprocessing 模块。QueueListener 位于消费一侧，内部线程不断从队列取出 LogRecord，并在这个线程里调用一个或多个实际 handler。官方文档把它们设计成配对使用的组件。

这条管线适合 Web 请求线程、任务线程或其它不希望被文件写入拖慢的代码。它解决的是“日志处理动作不要占用生产者线程”，不是把日志变成可靠消息队列，也不是自动保证进程崩溃前的记录一定落盘。

用 QueueHandler 把日志放进后台队列

先创建一个队列，再让业务 logger 只挂载 QueueHandler。真正输出用的 StreamHandler 不要同时挂在业务 logger 上，否则同一条记录可能一边入队、一边同步输出。

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

log_queue = queue.Queue()

# 生产者只负责把 LogRecord 放入队列，不直接写终端或文件。
queue_handler = QueueHandler(log_queue)

# 输出 handler 放到监听端，格式化和写出都在后台线程完成。
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_handler.setFormatter(
    logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
)

listener = QueueListener(
    log_queue,
    console_handler,
    respect_handler_level=True,
)

logger = logging.getLogger("orders")
logger.setLevel(logging.DEBUG)
logger.addHandler(queue_handler)
logger.propagate = False

# 先启动消费者，再让业务线程开始产生日志。
listener.start()
logger.debug("这条记录进入队列，但不会交给 INFO 级 console_handler")
logger.info("订单处理开始")

这里设置了两套级别：logger 决定哪些记录进入队列，console_handler 决定后台输出哪些级别。当 respect_handler_level=True 时，监听器会在分发给具体 handler 前尊重它的级别；不设置这个参数时，监听器的旧行为是把每条记录都交给初始化时传入的 handler。

让后台线程承接多个输出目标

一个 QueueListener 可以接收多个 handler。例如同一条记录既写终端又写文件，但每个 handler 的级别和 formatter 可以独立设置。多个生产者也可以共享同一个监听器，这比为每个输出 handler 单独创建线程更容易控制。

import logging
from logging.handlers import RotatingFileHandler

file_handler = RotatingFileHandler(
    "service.log",
    maxBytes=5 * 1024 * 1024,
    backupCount=3,
    encoding="utf-8",
)
file_handler.setLevel(logging.WARNING)
file_handler.setFormatter(
    logging.Formatter("%(asctime)s %(levelname)s %(message)s")
)

# 同一个监听线程把记录分发给终端和文件两个目标。
listener = QueueListener(
    log_queue,
    console_handler,
    file_handler,
    respect_handler_level=True,
)

同一个监听器可以服务多个 QueueHandler。文件滚动只解决文件大小管理，不改变队列的异步边界；初始化后不要直接改动监听器的内部 handler 集合，若配置变化应在明确的生命周期边界重新构造。

退出时先停止 listener，再清理日志资源

后台日志管线最容易被忽略的是生命周期。应用退出前应停止监听器，让它结束自己的工作线程；之后再移除生产者侧 handler，最后关闭文件等实际输出资源。不要在仍有生产者写入时直接关闭队列或文件。

try:
    # 业务代码通过 logger 产生日志。
    logger.info("开始处理任务")
    run_business_task()
except Exception:
    # 异常信息仍由 QueueHandler 交给后台输出。
    logger.exception("任务处理失败")
    raise
finally:
    # 先停止消费线程，再断开生产者，最后释放实际输出资源。
    listener.stop()
    logger.removeHandler(queue_handler)
    console_handler.close()
    file_handler.close()

listener.stop() 是关闭顺序的关键。它会停止监听线程；若业务还会继续产生日志，就不应提前执行这段清理逻辑。生产环境可以把启动和停止封装进应用生命周期钩子，保证异常退出路径也能经过同一套收尾动作。

队列类型和异常边界怎么选

单进程、多线程服务通常使用 queue.Queue。若日志要跨进程传递，才考虑 multiprocessing 的队列；官方文档特别提醒，使用多进程时不要把 multiprocessing.SimpleQueue 当作 QueueListener 的队列替代品，而应使用 multiprocessing.Queue。

常见问题

QueueHandler 自己会创建后台线程吗？

不会。它的主要职责是把记录发送到队列。真正从队列取记录并在独立线程调用输出 handler 的是 QueueListener。

为什么日志重复输出？

常见原因是业务 logger 同时挂了 QueueHandler 和 StreamHandler，或者记录继续向 root logger 传播。检查 handler 挂载位置，并按需要设置 propagate=False。

可以只用 QueueHandler 不启动 QueueListener 吗？

不适合作为完整管线。记录会进入队列但没有消费者处理；除非你有另一个明确的消费者，否则应同时启动 QueueListener。

后台日志一定比同步日志快吗？

它减少了生产者线程等待输出的时间，但增加了队列、线程和退出管理成本。最终吞吐仍受 formatter、文件系统和外部 handler 速度影响。

总结一下：让 logger 只挂 QueueHandler，把真实输出 handler 交给 QueueListener；用 respect_handler_level 控制分发级别；单进程优先使用 queue.Queue，跨进程再选择匹配的多进程队列；退出时先停止 listener，再移除和关闭 handler。这样“交给后台”才是清晰可维护的日志管线，而不是简单地把写日志调用包进一个线程。