Python 日志上下文自动注入的实现

loggeradapter 是最轻量可靠的上下文注入方式，因其为标准库原生机制，不依赖第三方、不污染全局、不改变调用习惯，仅需封装 logger 即可自动注入上下文字段。

为什么 LoggerAdapter 是最轻量又可靠的上下文注入方式

因为它是标准库原生支持的机制，不依赖第三方、不污染全局状态、不改变日志调用习惯。你只需要在每次获取 logger 时套一层适配器，后续所有 logger.info()、logger.Error() 都会自动带上你传入的上下文字段。

常见错误是试图在 formatter 里硬塞变量，或者用 threading.local 手动维护上下文——前者无法跨线程/协程传递，后者容易泄漏、难清理、和异步框架（如 asyncio）冲突。

使用场景：Web 请求 ID、用户 ID、任务批次号这类“一次请求/任务生命周期内固定”的字段；不适合存高频变动的局部变量（比如循环里的 i）。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 始终用 LoggerAdapter 的 extra 参数传字典，不要直接改 logger.extra（它不存在）
• 避免在 extra 中传可变对象（如 dict、list），防止被后续日志修改影响输出
• 如果用 structlog 或 loguru，别硬套这个方案——它们有自己更自然的绑定方式

import Logging logger = logging.getLogger("myapp") adapter = logging.LoggerAdapter(logger, {"request_id": "abc123", "user_id": 42}) adapter.info("login succeeded")  # 输出自动含 request_id 和 user_id

Filter 方法能解决跨模块/跨线程上下文丢失问题吗

能，但必须配合 LogRecord 动态注入，且只对当前 handler 生效。它的核心价值不是“加字段”，而是“按需补字段”——比如你在中间件里把 request_id 存到了 threading.local，就可以用 filter 在每条日志生成前把它捞出来塞进 record。

容易踩的坑：

• 忘记在 filter() 里返回 True，导致日志被静默丢弃
• 在多线程环境里误用全局变量或未初始化的 threading.local 属性，造成上下文串扰
• filter 中做耗时操作（如查数据库、发 http 请求），拖慢整个日志链路

性能影响很小，但兼容性要注意：asyncio 任务中 threading.local 不起作用，得换 contextvars.ContextVar。

import logging import threading _local = threading.local() <p>class ContextFilter(logging.Filter): def filter(self, record): record.request_id = getattr(_local, "request_id", "unknown") return True  # 必须返回 True，否则日志被过滤掉

用 contextvars 支持 asyncio 场景下的上下文穿透

这是 python 3.7+ 唯一推荐的异步上下文方案。它比 threading.local 更底层、更安全，能跨 await 边界保留值。但注意：它不会自动注入到日志 record，必须和 Filter 或 LoggerAdapter 配合使用。

典型错误是以为声明了 ContextVar 就万事大吉——没在 record 上显式赋值，formatter 依然看不到。

使用场景：fastapi、Starlette、tornado 异步服务；或任何用了 async/await 且需要日志带 trace_id 的地方。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 定义 ContextVar 时给默认值（如 ContextVar("request_id", default="")），避免 LookupError
• 在请求入口（如中间件）调用 var.set(value)，不要在日志调用点重复 set
• filter 中用 var.get() 取值，别用 var.reset(Token) ——那是清理用的，不是读取用的

import contextvars import logging <p>request_id_var = contextvars.ContextVar("request_id", default="")</p><p>class AsyncContextFilter(logging.Filter): def filter(self, record): record.request_id = request_id_var.get() return True

Formatter 模板里怎么安全引用注入的字段

用 %(request_id)s 这种老式字符串格式语法，不要用 f-String 或 {request_id}。因为 logging 模块内部用的是 % 格式化，其他写法会直接报 KeyError 或静默忽略字段。

容易被忽略的点：

• 字段名必须和你注入到 extra 或 record 中的 key 完全一致（大小写、下划线都不能错）
• 如果字段可能为 None，模板里写成 %(request_id)s 会炸，要先在 filter 或 adapter 里转成字符串（如 str(var.get() or "")）
• 自定义 formatter 继承 logging.Formatter 时，别重写 format() 去手动拼接——破坏了 lazy evaluation，失去性能优势

兼容性上，%(xxx)s 写法从 Python 2.7 到 3.12 全版本有效，最稳。

formatter = logging.Formatter(     "%(asctime)s %(name)s %(levelname)s [req=%(request_id)s] %(message)s" )

事情说清了就结束。关键不在“怎么加字段”，而在于字段生命周期是否和你的执行模型对齐——同步用 threading.local，异步必须用 contextvars，混用会出不可预测的空值或错值。