当前位置：首页 > 文章列表 > 文章 > python教程 > Python logging按请求注入上下文字段的过滤器方案

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

来源：17golang原创 2026-09-20 14:42:01 0浏览收藏

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

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

要点速览

ContextVar 按当前线程或异步任务隔离值，适合请求级上下文。
过滤器应绑定到实际输出日志的 Handler，并为缺省字段提供兜底值。
入口保存 set() 返回的 token，在 finally 中 reset()，避免复用线程时串上下文。

先把请求字段放进 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)

Python ContextVar 保存 request_id 和 user_id，再交给 logging Filter 注入 LogRecord 的结构说明图 — 图1：ContextVar 到日志记录的输入关系说明图，不是运行截图。

不要只调用 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("订单查询完成")

Python logging Handler 接收 LogRecord、Filter 注入 request_id 和 user_id、Formatter 输出日志的关系图 — 图2：Handler、Filter 与 Formatter 的字段流转说明图，不是运行截图。

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

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

场景	建议	容易忽略的点
同步请求	入口 set，finally reset	线程复用不会自动清理业务值
asyncio 任务	每个任务建立自己的上下文	创建后台任务前确认需要传播哪些字段
多 Handler	把字段注入放在需要输出它的 Handler	不同 Formatter 的字段集合可能不同

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