Python logging.handlers.QueueListener 停机怎么保证日志不丢：队列排空、超时与异常收尾

线上服务准备退出时，主线程已经返回了，日志文件却少了最后几行：请求完成记录、异常堆栈和停机原因往往正好落在这段空档里。使用 QueueHandler 和 QueueListener 把慢日志移到后台线程后，真正的风险不在“能不能异步写”，而在“谁先停止生产、谁负责排空、谁确认监听线程已经结束”。

优雅停机的关键顺序是：先让业务停止产生新日志，再调用 QueueListener.stop() 发送结束信号并等待监听线程收尾，最后检查输出文件和进程退出结果；不要把 sys.exit() 当成日志刷盘机制。

先把“日志资产”与停机边界分开

一条进入队列的 LogRecord，并不等于已经落盘。可以把它的生命周期拆成四段：业务线程创建记录，QueueHandler 放入队列，QueueListener 线程取出并交给文件 handler，最后由 handler 写入并刷新文件。任何一段提前结束，都会留下“代码看起来执行成功，日志却找不到”的假象。

为什么直接退出会留下队列尾部记录

QueueListener 在单独线程里取记录，主线程调用 logging.info() 后很快就能继续执行。服务收到 SIGTERM 后，如果处理函数直接返回，解释器退出时监听线程可能还没有处理完队列尾部；Python 官方文档也明确提醒，没有在退出前调用 stop()，队列中可能仍有未处理的记录。

这里先别急着给日志模块加固定延时。延时只能碰运气：日志少时浪费时间，日志多时又不够。更可靠的做法是使用监听器自己的结束协议，让后台线程收到 sentinel 后停止，并等待它真正结束。

一套可复查的停机实现

下面的示例把业务写入和停机收尾放在同一个生命周期对象里。生产环境中，stop_logging() 应该在业务停止接收新请求之后调用，而不是在任意异常分支里抢先执行。

import logging
import logging.handlers
import queue

log_queue = queue.Queue()
file_handler = logging.FileHandler("service.log", encoding="utf-8")
file_handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s %(name)s event=%(message)s"
))

listener = logging.handlers.QueueListener(
    log_queue, file_handler, respect_handler_level=True
)
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(logging.handlers.QueueHandler(log_queue))
listener.start()

def stop_logging():
    # 1. 先由上层停止接收新请求，再进入这里
    listener.stop()       # 发送 sentinel，并等待监听线程结束
    file_handler.close()  # 关闭文件资源

stop() 不是“睡眠几秒后退出”，它会请求监听线程结束并等待线程完成。调用它之后再关闭文件 handler，顺序才不会把最后一批记录送进已经关闭的文件对象。

异常收尾要保留最后一条证据

停机本身也可能遇到文件权限、磁盘写满或 handler 自定义逻辑异常。建议给每次停机生成一个短的事件编号，在开始收尾和收尾完成处分别写入；验收时查这个编号，而不是只数日志行数。若 stop() 抛错，先保留原异常，再执行必要的资源关闭，避免把真正的写入故障覆盖成一个普通退出。

shutdown_id = "shutdown-20260825-001"
logger = logging.getLogger("service.lifecycle")

try:
    logger.info("shutdown_begin %s", shutdown_id)
    stop_logging()
except Exception:
    # 这里仍应把异常交给进程级监控；不要静默吞掉
    raise
finally:
    # 上层还应确认服务不再接收新请求
    print("shutdown_finished", shutdown_id)

Python 3.14 上下文管理器与旧版本怎么选

Python 3.14 为 QueueListener 增加了上下文管理器支持，进入 with 时启动监听器，离开时停止监听器。它适合生命周期天然包在一个代码块里的短任务；长驻服务通常仍需要把“停止接收请求”和“停止日志监听”接到同一个信号处理流程里。

with logging.handlers.QueueListener(log_queue, file_handler) as listener:
    run_one_job()
# 离开 with 后，listener 已经完成停止流程

如果项目还要支持 Python 3.11 或更早版本，不要直接依赖这个新语法。显式调用 start()、stop() 是更清晰的兼容写法，也方便把停机日志、退出码和监控告警接到同一处。

发布前用三条样本验收

1. 正常路径：写入带唯一 event_id 的完成日志，停止接收新任务后调用 stop()，在文件中检索到该编号。
2. 异常路径：让文件 handler 返回可观测的写入错误，确认进程记录错误并关闭资源，没有把异常吞掉。
3. 尾部路径：在停止信号前连续写入一小批编号日志，比较最后一个编号与文件最后一条记录，确认没有静默截断。

如果测试偶尔缺一条，先检查是否仍有代码在 stop() 之后调用 logger，再检查 handler 是否被其他模块提前关闭。不要先加 time.sleep(1)；它没有表达“队列已排空”的事实，也无法覆盖磁盘变慢的场景。

相关问题

调用 stop() 后还需要手动清空 queue.Queue 吗？

正常使用 QueueListener 时不需要。它会通过 sentinel 让监听线程结束，线程会先处理自己已经取到的队列内容；真正要确认的是业务已经停止继续生产。

为什么 stop() 之后文件里仍然没有日志？

优先检查日志是否走到了同一个 QueueHandler、文件路径是否是预期路径，以及 FileHandler 是否在监听器之前被关闭。再用唯一事件编号区分“没入队”和“入队但写入失败”。

QueueListener 能替代所有日志可靠性方案吗？

不能。它解决的是进程内异步处理，不提供跨进程持久队列、磁盘满时的重试或远端日志服务的确认语义。高可靠场景仍需明确丢失策略和外部收集系统。

落地清单

把 QueueListener 接进服务时，至少留下三项可审计证据：停止生产的时间点、监听线程完成停止的结果、最后一条带事件编号的日志。这样发生日志缺口时，能判断是队列没排空、handler 写入失败，还是业务在收尾之后仍继续产生日志，而不是靠猜测调整等待秒数。