直接用 logging.info() 在高并发下会拖慢服务，因其默认 Handler 同步 I/O 且受全局锁限制，导致线程/协程阻塞；QueueHandler+QueueListener 通过队列解耦记录与落地，并需配置队列大小、propagate=False、显式 formatter 及 exc_info 序列化处理。

为什么直接用 logging.info() 在高并发下会拖慢服务

因为默认的 StreamHandler 和 FileHandler 是同步写入的，每次调用 logging.info() 都会阻塞当前线程，等 I/O 完成才返回。在 Web 服务（如 Flask/FastAPI）或异步任务中，这会让一个请求卡住整个协程或线程池资源。

常见现象包括：QPS 突然下降、响应延迟毛刺明显、日志量一上来 CPU 负载不高但吞吐骤降。

• 根本原因不是日志内容多，而是日志 I/O 串行化 + 全局锁（logging._lock）
• 即使换成 RotatingFileHandler，也只是缓解磁盘满问题，不解决阻塞
• asyncio 中直接调用 logging.info() 会打破事件循环节奏，尤其在 await 密集路径里

QueueHandler + QueueListener 是怎么解耦的

核心思路是把「日志记录动作」和「日志落地动作」拆开：应用线程只往队列发日志对象，后台单独起线程消费并真正写文件。

关键组件：

• QueueHandler：继承自 Handler，重写了 emit()，只做 self.queue.put_nowait(record)
• QueueListener：接收队列，启动 1+ 个工作线程，从队列取 LogRecord 后交给传入的 handlers（比如 FileHandler）处理
• 队列类型建议用 queue.Queue（非线程安全的 collections.deque 不行）

注意：QueueListener 内部线程不参与事件循环，所以它天然兼容 asyncio 服务——你只需要确保应用层日志调用不进 I/O，就完了。

论小文

可靠的论文写作助手，包含11种学术写作类型，万字论文一键生成，可降重降AIGC，参考文献真实可标注，图表代码均可自定义添加。

下载

实际部署时必须改掉的三个默认配置

光套上 QueueHandler 不够，不调整配套设置，照样卡死或丢日志。

• 队列大小不能设为无限：queue.Queue(maxsize=1000) 更稳妥，避免内存爆掉；设太小（如 10）会导致 put_nowait() 抛 queue.Full，得包 try/except
• QueueListener 的 handlers 必须关闭 .setLevel() 外的其他 handler 的 propagate=False，否则日志会重复输出到 root logger
• 所有下游 handler（比如 FileHandler）要显式调用 handler.setFormatter(...)，因为 QueueListener 不自动继承 formatter

示例关键片段：

import logging
from logging.handlers import QueueHandler, QueueListener
import queue
log_queue = queue.Queue(maxsize=1000)
queue_handler = QueueHandler(log_queue)
根 logger 只加 queue_handler
root_logger = logging.getLogger()
root_logger.addHandler(queue_handler)
root_logger.setLevel(logging.INFO)
真正写文件的 handler（注意：要自己设 formatter）
file_handler = logging.FileHandler("app.log")
file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
listener = QueueListener(log_queue, file_handler)
listener.start()  # 必须手动 start

异步服务里还要额外防一个坑：LogRecord 序列化失败

QueueHandler 会把 LogRecord 对象放进队列，而默认 queue.Queue 是线程安全的，但某些字段（比如 exc_info、args 里带不可序列化对象）在跨线程传递时可能出问题，表现为后台线程静默退出或抛 TypeError。

• 典型触发场景：用 logging.exception("msg") 或 logger.error("err", exc_info=True)
• 解决方案：在 QueueListener 启动前，给所有下游 handler 加一层封装，确保 record.exc_info 被提前格式化成字符串
• 更简单做法：全局替换 logging.Logger.makeRecord，但风险高；推荐用 logging.Filter 在 filter() 方法里处理 record.exc_text = traceback.format_exception(*record.exc_info)

这个点容易被忽略，因为错误不报在主线程，日志也不出来——表现就是「某类错误突然不写磁盘了」。