Python logging 多模块共享上下文时怎么用 LoggerAdapter

多模块服务里，最稳妥的做法不是让每个模块自己拼接 request_id，而是在请求入口创建一个 LoggerAdapter，把它传给订单、库存等模块；各模块只使用这个适配后的 logger，Handler 和 Formatter 集中配置一次。这样上下文会随每条 LogRecord 走完整条日志链。

先记住一句话：LoggerAdapter 负责把上下文放进记录，Handler 负责把记录送到输出端，Formatter 负责读取字段并排版。多模块共享上下文时，通常只需要共享适配后的 logger，不要在每个模块重复添加 Handler。

一、先把 Handler 和 Formatter 集中配置

Python logging 的 logger 按名称形成层级。模块 logger 产生的记录可以向父 logger 传播，最终交给根 logger 上的 Handler。入口处只配一个 StreamHandler，能避免“每个模块都打印一次”的重复输出。

import logging

def configure_logging():
    # 默认值让第三方或未使用 Adapter 的记录也能正常格式化
    formatter = logging.Formatter(
        "%(asctime)s %(levelname)s %(name)s "
        "[%(service)s request=%(request_id)s] %(message)s",
        defaults={"service": "unknown", "request_id": "-"},
    )
    handler = logging.StreamHandler()
    handler.setFormatter(formatter)

    root = logging.getLogger()
    # 入口统一设置级别和 Handler，业务模块不要再次 addHandler
    root.setLevel(logging.INFO)
    root.addHandler(handler)

Formatter 中的字段最终来自 LogRecord。如果格式串写了 %(request_id)s，但某条记录没有这个属性，格式化阶段就会出错，所以这里用 defaults 给普通记录留出兜底值。生产项目还应保证配置函数只执行一次，避免重复注册 Handler。

二、为一次请求创建 LoggerAdapter

LoggerAdapter 的核心工作是通过 process() 把构造时的 extra 放进日志调用的关键字参数。把 Adapter 的生命周期限制在一次请求内，就不会把上一个请求的标识带到下一个请求。

import logging

def handle_request(request_id: str):
    # 每个请求创建自己的上下文，不修改全局字典
    base_logger = logging.getLogger("app")
    request_logger = logging.LoggerAdapter(
        base_logger,
        {"service": "checkout", "request_id": request_id},
    )
    request_logger.info("开始处理订单查询")
    load_order(request_logger, 42)

def load_order(logger: logging.LoggerAdapter, order_id: int):
    # 业务函数只使用传入的 Adapter，不重复拼接上下文
    logger.info("读取订单 id=%s", order_id)

handle_request("req-7f31")

这里的 service 和 request_id 会成为当前记录的属性，Handler 不需要知道它们来自哪个模块。业务函数接收的是“能记录日志的对象”，因此可以继续使用 info()、warning() 和 exception() 等方法。

三、把同一个适配后的 logger 传过多个模块

多模块共享上下文时，入口函数传递 Adapter 比让每个模块读取全局变量更清楚。订单模块和库存模块可以各自保留 logging.getLogger(__name__) 用于模块名，但真正写这次请求日志时，使用入口传下来的 Adapter。

def check_stock(logger, sku: str):
    # inventory 模块不创建新 Handler，也不丢失 request_id
    logger.info("检查库存 sku=%s", sku)
    return True

def create_order(logger, sku: str):
    # orders 模块复用同一个请求上下文
    if check_stock(logger, sku):
        logger.info("订单创建成功 sku=%s", sku)

如果模块还需要记录自己的固定字段，可以创建一个基于模块 logger 的 Adapter，但要先明确字段覆盖规则。更简单的项目直接沿用入口 Adapter，Formatter 中的 %(name)s 则显示基础 logger 的名称，便于按模块排查。

四、字段缺失、重复输出和 merge_extra 怎么排查

Python 3.13 为 LoggerAdapter 增加了 merge_extra。默认行为仍以 Adapter 自己的 extra 为准，调用 logger.info(..., extra={...}) 不会自动合并；需要一次调用附加字段时，显式构造 logging.LoggerAdapter(base_logger, base_context, merge_extra=True)。如果运行环境低于 3.13，就不要把这个参数写进公共代码，可以把临时字段放入消息参数，或在自定义 Adapter 的 process() 中定义兼容合并规则。

最后检查一遍职责边界：模块只产生日志事件，Adapter 管上下文，Handler 管去哪里，Formatter 管长什么样。这个边界稳定后，新增模块只需要获取自己的 logger 或接收已有 Adapter，不需要复制整套日志配置。

常见问题

LoggerAdapter 会替代模块级 logger 吗？

不会。它包装的是一个已有 logger，主要增加上下文处理；模块仍可使用 logging.getLogger(__name__) 保留层级和名称。

为什么只配置根 Handler 也能收到子模块日志？

因为非根 logger 默认会向父级传播。若某个模块把 propagate 设为 False，或者给自己添加了独立 Handler，输出路径就会改变。

Formatter 的自定义字段应该放在哪里？

字段值应进入当前 LogRecord，LoggerAdapter 的 extra 是常用入口；Formatter 只负责读取和展示，不负责猜测请求上下文。