Python 日志怎样给每条记录附加请求上下文

Python 日志可以用 extra 给 LogRecord 增加请求字段，再用请求级 LoggerAdapter 把固定上下文附加到经它发出的每条记录。关键不是反复拼接 request_id，而是明确谁负责提供字段、谁负责展示，以及单条日志能不能覆盖请求身份。适配器不会自动接管第三方库或绕过它发出的日志。

官方文档地址：https://docs.python.org/3.14/library/logging.html；上下文用法说明：https://docs.python.org/3.14/howto/logging-cookbook.html。下文主示例面向 Python 3.13 及以上，另给出旧版合并写法。

日志里少了请求号，不一定是请求没有执行

考虑一个用于讲解的故障场景：摘要接口原本只记消息，后来格式串加入 request_id；入口日志正常，业务函数的记录却缺失，维护日志也出现格式化错误。这不是实际生产事故记录，下面代码没有在本机执行，结果判断来自字段契约。

排查时可以沿修改顺序还原：最初所有调用都直接用 logger；接着只给入口加 extra；最后 Formatter 开始强制读取自定义字段。触发条件是“同一个输出格式接收了没有这些字段的记录”。业务执行成功与日志输出成功是两件事，不应因为看不到日志就认定业务函数未运行。

extra 提供属性，Formatter 只负责显示

extra 的键进入 LogRecord 的属性空间，不会自动进入 message，也不是普通消息参数。request_id、route 是本文自定义字段；message、name、levelname 等系统字段不能拿来当自定义键覆盖。字段冲突和格式化缺字段是不同问题：前者可能在创建记录时抛出异常，后者发生在输出格式化阶段。

本文中，LoggerAdapter 持有请求字典并关联底层 Logger；LogRecord 承载自定义属性；Formatter 引用所需字段；StreamHandler 使用 Formatter 输出文本。这些是静态职责关系，不是新增的日志组件。

让同一次请求始终使用同一个适配器

下面用两次独立函数调用模拟不同请求。入口为每次调用创建新的上下文字典，并把适配器作为参数传给业务函数。示例只建立一个专用处理器，不修改应用根日志配置；集成进真实服务时，把配置留在应用启动阶段，不要每次请求执行一遍。

import logging

# 独立示例：配置只在应用入口执行，避免请求内反复添加处理器。
base = logging.getLogger("request_demo")
base.setLevel(logging.INFO)
base.propagate = False
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter(
    "%(levelname)s request=%(request_id)s route=%(route)s "
    "event=%(event)s %(message)s",
    defaults={"request_id": "-", "route": "-", "event": "-"},
))
base.addHandler(handler)

def handle(request_id, route):
    # 每个请求创建自己的字典；不要修改共享适配器来切换请求。
    log = logging.LoggerAdapter(
        base, {"request_id": request_id, "route": route},
        merge_extra=True,
    )
    load_summary(log)
    log.info("响应已准备", extra={"event": "response_ready"})

def load_summary(log):
    # 显式传递适配器，业务函数的日志才能继承同一份上下文。
    log.info("读取摘要", extra={"event": "summary_read"})

handle("demo-A", "/summary")
handle("demo-B", "/summary")
base.info("服务维护事件")

按代码推导，demo-A 的读取与响应记录应保留 demo-A，demo-B 同理；维护事件使用默认占位符。这里的 Formatter(defaults=...) 从 Python 3.10 起可用，用于缺字段时的显示兜底，不会把 request_id 真正注入原始记录。若下游消费的是 LogRecord 而不是格式化文本，不能依赖 defaults 生成字段。

这套方案的覆盖范围只有传入适配器的调用链。业务函数重新调用底层 base、其他模块的 logger 或第三方库 logger，都不会自动获得本请求字典。需要全局自动注入时应另行设计，而不能把这段局部方案宣传成全服务链路追踪。

单条 extra 为什么会丢，以及谁可以覆盖字段

LoggerAdapter 默认 merge_extra=False，单条日志传入的 extra 会被忽略，使用适配器自身的 extra。Python 3.13 增加了 merge_extra；开启后可以把请求字段与 event 等单条字段合并，同名字段由单条调用值覆盖。因此主示例约定业务调用只提供 event，不提供 request_id 或 route。

如果请求身份必须受保护，或需要兼容没有 merge_extra 的版本，可以使用下面这个自定义适配器。它有意采用比内置合并更严格的策略：检测身份键并报错，让错误尽早暴露。以下片段接在主例的配置之后；使用旧版时应把主例构造适配器的位置换为 RequestAdapter，并删除 merge_extra 参数。Formatter 的 defaults 仍要求 Python 3.10 及以上。

class RequestAdapter(logging.LoggerAdapter):
    def process(self, msg, kwargs):
        # 复制后合并，不原地修改请求字典；请求身份不允许单条调用覆盖。
        supplied = dict(kwargs.get("extra") or {})
        for key in ("request_id", "route"):
            if key in supplied:
                raise ValueError("单条日志不能覆盖请求身份字段")
        kwargs["extra"] = {**self.extra, **supplied}
        return msg, kwargs

# 旧版不传 merge_extra；其余调用方式与普通适配器一致。
log = RequestAdapter(base, {"request_id": "demo-C", "route": "/summary"})
log.info("读取摘要", extra={"event": "summary_read"})

合并时必须先复制映射。把 event 原地更新到 self.extra，会使本来属于单条日志的事件字段残留到后续日志；把共享对象里的 request_id 改成“当前请求”，则会让并发请求互相污染。logging 的输出锁不等于请求字典的隔离保证。

用这些边界场景防止修完又串号

这些是读者可执行的回归场景，不是本文已完成的测试报告。真实服务还要在现有日志配置下检查等级、处理器和重复传播；默认占位不能代替必填请求字段的业务约束。上下文仅收录必要标识，避免把完整请求体、令牌或个人敏感数据放进 extra。

每个请求都创建新的 Logger 可以吗？

通常保持模块或服务 Logger 稳定，再创建轻量请求适配器。不要把无限增长的请求号编码进 logger 名称。

Formatter 的默认值能补齐第三方库记录吗？

能在这个 Formatter 生成的文本中提供占位，但不会让第三方记录拥有真实请求身份，也不保证其他输出路径具备同样字段。

异常日志也能附加上下文吗？

经同一个适配器调用 exception 可以继续携带上下文；异常信息与 extra 是两类参数。不要为了携带请求号而手动拼接或吞掉异常。

修复的核心是让“请求身份固定、单条事件独立、格式化允许缺省”成为明确契约。extra 负责记录属性，LoggerAdapter 负责减少重复传参；能否覆盖所有日志，最终取决于调用是否真正经过该适配器。