Python logging按请求注入上下文字段的过滤器方案

Python 服务一旦同时处理多个请求，只把 request_id 放进全局变量，日志就可能出现“请求 A 的编号配在请求 B 的报错上”。更稳妥的做法是用 contextvars.ContextVar 保存请求上下文，再让 logging.Filter 在日志记录生成后注入字段。这样业务函数仍然可以直接使用普通 logger，不需要层层传递参数。

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

先把请求字段放进 ContextVar

ContextVar 的重点不是“全局可见”，而是“在当前执行上下文中可见”。它从 Python 3.7 起提供上下文局部存储，官方文档也明确建议并发代码用它替代容易串值的状态容器。变量应该在模块级创建，默认值则负责覆盖健康检查、启动日志等没有请求入口的记录。

import logging
from contextvars import ContextVar

request_id_var = ContextVar("request_id", default="-")
user_id_var = ContextVar("user_id", default="-")

def handle_request(request_id: str, user_id: str) -> None:
    # 保存旧上下文，确保线程池或异步任务复用后不会遗留本次请求
    request_token = request_id_var.set(request_id)
    user_token = user_id_var.set(user_id)
    try:
        logging.getLogger("order").info("开始处理订单")
    finally:
        # 无论业务成功还是异常，都恢复进入请求前的值
        request_id_var.reset(request_token)
        user_id_var.reset(user_token)

不要只调用 set() 而不保存 token。在线程池里，请求结束后线程通常还会继续服务下一次请求；不 reset 时，下一条没有显式设置字段的日志可能继续带着旧编号。

让 Filter 统一补齐 LogRecord 字段

过滤器可以修改传入的 LogRecord，因此很适合把上下文字段集中注入。下面的实现只做两件事：读取当前上下文，并保证 Formatter 使用的字段永远存在。过滤器返回 True 表示继续输出，不把它当成业务条件过滤器使用。

class RequestContextFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        # 统一注入字段，避免 Formatter 遇到缺失属性而报错
        record.request_id = request_id_var.get()
        record.user_id = user_id_var.get()
        return True

handler = logging.StreamHandler()
handler.addFilter(RequestContextFilter())
handler.setFormatter(logging.Formatter(
    "%(levelname)s request=%(request_id)s user=%(user_id)s %(message)s"
))
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(handler)

# 业务模块只拿 logger，不必接收 request_id 参数
logging.getLogger("order").info("订单查询完成")

把过滤器挂在 Handler 通常更容易控制：多个 Handler 可以分别决定是否需要这些字段。若只挂在父 Logger 上，来自子 Logger 的记录不一定经过该 Logger 的过滤器；另外，重复给祖先和子 Logger 绑定 Handler 还可能造成重复输出。

同步线程和 asyncio 都要检查的边界

日志格式中新增字段后，所有可能处理该记录的 Handler 都要有对应的兜底字段，否则某条第三方库日志没有经过预期过滤器时，Formatter 会抛出格式化异常。生产环境还要避免把完整 Cookie、Authorization 或身份证明直接放入 ContextVar；上下文隔离不等于敏感信息自动脱敏。

相关问题

为什么不用全局字典保存当前请求？

全局字典没有线程和任务隔离，同一时间的请求会互相覆盖。ContextVar 按执行上下文保存值，更适合并发请求。

Filter 应该挂在 Logger 还是 Handler？

需要确保最终输出字段时优先挂 Handler；只有确定所有目标 Logger 都会经过同一个过滤器时，才考虑挂在 Logger。

没有请求上下文的日志怎么办？

给 ContextVar 设置短横线等默认值，让启动日志、定时任务和异常兜底日志仍然可格式化，再用 logger 名称或任务名区分来源。