Python QueueHandler 为什么会丢日志：队列背压、QueueListener 与优雅退出

线上服务把日志改成异步写入后，业务请求确实轻了一点，但压测一上来，文件里的记录数量却比请求数少。问题通常不在 Formatter，而在 QueueHandler 把记录放进队列时没有处理好“队列已经满了”和“监听器正在退出”这两条边界。把这两处补上，才能既减少业务线程等待，又知道哪些日志应该降级、重试或直接暴露告警。

先看清 QueueHandler 到 QueueListener 的职责边界

QueueHandler 是生产端，它把日志记录放入指定队列；QueueListener 是消费端，从队列取出记录后交给真正的文件、控制台或网络 Handler。两者之间的队列就是缓冲区，不是无限存储。

例如一个容量为 1000 的 queue.Queue，消费者每秒只能写 500 条，而业务线程短时间送来 2000 条，剩下的记录必须有一个结果：阻塞生产者、丢弃低优先级记录，或者把压力反馈给上层。没有策略时，默认行为很容易让问题藏在标准错误输出里。

队列满时，别让错误处理把问题遮住

默认的 QueueHandler.enqueue() 使用非阻塞入队。队列满时，记录可能进入 handleError()，而生产线程未必得到一个足够醒目的业务信号。开发环境里这很方便，生产环境里却容易形成“接口成功、审计日志缺口”的错觉。

可以继承一个很小的 Handler，把满队列次数单独计数。这里不建议在 emit() 中等待很久，因为日志本来就是为了观察业务；如果日志反过来拖垮业务，故障会扩大。

import logging
import queue
from logging.handlers import QueueHandler

class CountingQueueHandler(QueueHandler):
    dropped = 0

    def enqueue(self, record):
        try:
            self.queue.put_nowait(record)
        except queue.Full:
            type(self).dropped += 1

log_queue = queue.Queue(maxsize=1000)
root = logging.getLogger("service")
root.setLevel(logging.INFO)
root.addHandler(CountingQueueHandler(log_queue))

示例把低优先级记录的降级点集中在一个地方，便于加指标。实际项目还应区分访问日志、审计日志和错误日志：访问日志可以采样，审计日志不能静默丢弃，错误日志至少要有独立的计数器或备用输出。

QueueListener 的退出顺序决定尾部日志是否完整

程序收到停止信号后，最容易犯的错是马上调用 listener.stop()，同时还有请求线程在写日志。此时新记录可能来不及入队，队列里已有的记录也可能没有按照业务预期完成核对。

更稳妥的顺序是：先让服务停止接收新任务；再等待现有生产者返回；然后停止 QueueListener，让它把队列中的记录交给目标 Handler；最后关闭文件 Handler。退出动作完成后，再读取丢弃计数和队列长度。

listener.start()
try:
    serve_requests()
finally:
    stop_accepting_requests()
    wait_for_inflight_requests()
    listener.stop()
    file_handler.close()

    if CountingQueueHandler.dropped:
        raise RuntimeError(
            f"日志队列丢弃 {CountingQueueHandler.dropped} 条"
        )

如果服务框架有自己的 shutdown hook，就把这段顺序接到框架生命周期里，不要让多个 signal handler 各自关闭一部分组件。尤其不要先关闭目标文件，再让监听器继续消费，否则最后几条记录会变成写入异常。

用四个数字验收异步日志链路

一次压测至少保存四个数字：业务侧提交数、成功入队数、消费者写入数、丢弃数。理想关系是“提交数 = 成功入队数 + 明确丢弃数”，而“成功入队数 = 写入数 + 退出时仍未消费数”。退出时仍未消费数应为零，否则就不能把这次运行当成日志完整。

可以在测试里使用唯一序号而不是依赖时间戳。时间戳在多线程环境里可能相同，唯一序号更适合核对缺口：

expected = {f"event-{i}" for i in range(5000)}
for i in range(5000):
    logger.info("event-%d", i)

# 等待服务退出后读取文件，再比较实际行中的 event-N
missing = expected - written_events
assert not missing, sorted(missing)[:10]

生产环境不要把完整日志内容复制到指标标签里。指标只放队列长度、丢弃计数、消费者处理耗时和最后一次成功写入时间；具体缺失序号留在测试或采样日志中。

常见问题

把队列改成无限容量就不会丢日志吗？

不能。无限容量只是把压力转移到内存，消费者持续落后时最终仍可能触发内存上涨或进程被系统终止。容量和降级策略需要一起设计。

错误日志也可以直接丢弃吗？

不建议。错误日志、审计日志和访问日志的可靠性要求不同，至少要为前两类保留备用输出、独立计数或阻塞式通道，并在文档里写清故障时的取舍。

为什么退出后文件里还少最后几行？

通常是生产者还没有结束就停止了监听器，或者文件 Handler 已关闭但队列仍在消费。先停接收、等待进行中的请求，再停止监听器并关闭文件，最后做数量核对。

QueueHandler 和 QueueListener 的价值是把日志写入从业务路径移开，但它们不会自动解决容量、可靠性和生命周期问题。把队列满、消费者落后、退出排空分别做成可观察的状态，再用唯一序号压测，才能知道这条异步链路是真的可用。