Python logging QueueListener 停止时怎么保证剩余日志写完

用 QueueHandler 把日志放进队列后，程序退出前必须显式调用 QueueListener.stop()。它不是“立即杀掉线程”，而是向队列追加一个停止哨兵，再等待监听线程结束；因此，只要所有生产者已经停止写日志，哨兵前面的记录就会先交给文件处理器。真正容易出错的地方，是生产者还在入队时就开始关闭监听器。

安全的关闭顺序是：停止新的日志来源 → 调用 listener.stop() 排空已有队列 → 调用文件处理器的 close() 释放文件资源。不要用“睡眠几秒”代替这三个动作。

QueueListener.stop 真正保证了什么

官方实现的监听线程不断从队列取出记录，遇到普通记录就调用处理器，遇到内部哨兵才退出。stop() 做的事情是把哨兵放进队列，然后 join() 等待线程结束。队列采用先进先出时，已经排在哨兵前的记录会先处理。

这是一种“队列顺序保证”，不是事务提交，也不是磁盘损坏恢复。若 QueueHandler 使用有界队列且入队时抛出 queue.Full，那条日志可能早已被 handleError() 处理；若文件系统或具体处理器写入失败，stop() 也不会把失败内容重新生成。

从零做一个可验收的文件日志小项目

下面的例子让业务线程只做入队，监听线程负责慢速文件写入。示例用编号而不是随机文本，便于最后判断尾部记录是否完整。

import logging
import logging.handlers
import queue
from pathlib import Path

log_path = Path("queue-demo.log")
records = queue.Queue()  # 使用先进先出队列，保留入队顺序
file_handler = logging.FileHandler(log_path, mode="w", encoding="utf-8")
file_handler.setFormatter(logging.Formatter("%(message)s"))  # 只保留验收需要的编号
listener = logging.handlers.QueueListener(records, file_handler)
logger = logging.getLogger("queue-demo")
logger.setLevel(logging.INFO)
logger.propagate = False  # 避免同一条记录又传播到根日志器
logger.addHandler(logging.handlers.QueueHandler(records))

listener.start()
try:
    for number in range(1, 101):
        logger.info("record-%03d", number)  # 业务线程快速入队，不直接碰文件
finally:
    # 关闭生产者后，stop 才能把哨兵稳定地放在最后一条业务日志之后
    listener.stop()
    file_handler.close()  # 监听线程结束后再释放文件句柄

lines = log_path.read_text(encoding="utf-8").splitlines()
if lines and lines[-1] == "record-100":
    print("drain ok: 100 records")  # 只输出验收结论，不把日志当作控制信号
else:
    raise RuntimeError(f"drain failed: got {len(lines)} records")  # 明确暴露尾部缺失

这个程序的关键不是 range(1, 101)，而是 try/finally 的边界：只要循环所在的生产阶段结束，后续就不再调用 logger 写入队列，stop() 才能稳定地把停止标记放在尾部。

关闭顺序：先停生产者，再停监听器

真实服务通常还有线程池、定时任务或消费者。应先让它们停止接收新任务并等待正在执行的任务返回，再进入日志收尾。下面这张图把“谁还能写日志”和“谁负责落盘”分开，排查时比盯着一个全局 shutdown() 更清楚。

如果你使用 Python 3.14，也可以把监听器放进 with 语句，让上下文退出时自动停止；但生产者仍要在离开上下文前完成，不能把“自动调用 stop”误认为“自动等待所有业务线程”。

如何判断最后一条日志真的写完

验收至少做两件事：第一，检查 listener.stop() 已返回；第二，再关闭文件处理器并读取文件内容。连续编号能发现中间缺口，最后一行能发现尾部没落盘。若日志来自多个生产者，不要把跨线程的全局顺序当成业务顺序；可以给每个生产者增加来源和序号，然后按来源分别核对。

还要区分“队列排空”和“业务日志绝不丢失”。QueueHandler 默认使用 put_nowait()，有界队列满时可能进入错误处理；若系统要求更强的投递保障，应在入队策略、容量、错误处理和外部日志系统上单独设计，不能只延长退出等待时间。

常见问题

调用两次 QueueListener.stop 会怎样？

当前实现允许在监听线程已清空后再次调用，第二次不会重新启动线程；但应用代码仍应把关闭动作集中管理，避免其他线程同时操作同一个 listener。

先关闭 FileHandler，再调用 stop 可以吗？

不建议。监听线程可能还在处理队列中的记录，应该先让 stop() 返回，再关闭文件处理器。

QueueListener.stop 能保证日志已经同步到磁盘吗？

它保证监听线程已经结束，但“线程处理完成”和存储设备的持久化语义不是同一层。需要更强保证时，还要结合处理器、文件系统和部署环境设计。

为什么不直接调用 logging.shutdown？

logging.shutdown() 适合统一关闭已注册的日志处理器；队列监听器的生命周期仍应由创建它的代码明确管理，尤其要先停止生产者，再等待 listener。