根本原因是 logging.LogRecord 默认不携带请求级上下文变量，trace_id 必须通过 contextvars + 自定义 Filter 显式注入；threading.local 在异步场景失效，contextvars 未正确传递或解析格式错误也会导致丢失。
Trace ID 为什么在 Python 日志里经常断掉
根本原因不是日志模块本身丢数据，而是 logging 的 LogRecord 默认不携带上下文变量，而 trace_id 属于请求级上下文，必须显式注入。如果你用的是 threading.local 或没配 contextvars，多线程、协程（尤其是 asyncio）下几乎必丢。
常见错误现象：log_record.trace_id 是 None 或空字符串；同一个请求里不同模块日志的 trace_id 不一致；异步视图中日志完全没 trace_id。
- Flask/Django 等同步框架：靠
threading.local能勉强撑住，但中间件顺序错、装饰器绕过、线程池任务会漏 - FastAPI/Starlette 等异步框架：
threading.local完全失效，必须用contextvars.ContextVar - 日志格式化器里直接写
%(trace_id)s却没提前注册字段，会静默忽略，不报错也不显示
怎么让 logging.Formatter 稳定读到 trace_id
不能依赖全局变量或函数局部变量，必须把 trace_id 绑定到 LogRecord 实例上——最可靠的方式是自定义 Filter，在每条日志生成前注入。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 定义一个
ContextFilter类，内部用contextvars.ContextVar(str)存trace_id，filter()方法里调record.trace_id = self.trace_id_var.get(None) - 在
Formatter的format()里访问record.trace_id，而不是尝试从record.__dict__里硬取未声明的 key - 务必在
Logger.addHandler()后立即加logger.addFilter(ContextFilter())，顺序反了就白搭 - 如果用了
structlog，别碰logging原生 filter，改用structlog.contextvars.bind_contextvars(trace_id=...)
示例关键片段：
import contextvars
import logging
trace_id_var = contextvars.ContextVar('trace_id', default=None)
class ContextFilter(logging.Filter):
def filter(self, record):
record.trace_id = trace_id_var.get()
return True
asyncio 场景下 trace_id 透传失败的典型原因
contextvars 在 asyncio 中是“任务隔离”的，但很多库（比如 aiohttp 中间件、fastapi 依赖注入）没主动 copy 上下文，导致子任务里 trace_id_var.get() 返回默认值。
- 用
asyncio.create_task(..., context=copy_context())显式传递，而不是裸调create_task() - FastAPI 中，在
Depends()函数开头手动trace_id_var.set(request.headers.get('X-Trace-ID'))，别指望 middleware 自动塞进 contextvar -
concurrent.futures.ThreadPoolExecutor执行阻塞操作时，contextvars不跨线程，得在 submit 前contextvars.copy_context()并用context.run()包裹目标函数 - 别在
async def里用logging.getLogger().info()直接打日志——此时还没 set 过trace_id_var，要确保 set 发生在 request handler 开头，且早于任何日志调用
日志输出里 trace_id 格式不统一怎么办
不是所有服务都用 X-Trace-ID，有的用 traceparent（W3C 标准），有的用 uber-trace-id，解析逻辑一错，透传就断。更麻烦的是，不同语言服务混用时，Python 往外发 HTTP 请求，header 写错格式会导致下游无法识别。
- 入库或发给 ELK 时，
trace_id字段必须是纯字符串（如0a1b2c3d4e5f6789），不能带00-前缀或-01后缀（那是traceparent全量值） - 用
opentelemetry-sdk时，get_current_span().get_span_context().trace_id返回的是 int，需转成 32 位十六进制小写字符串：f'{span_context.trace_id:032x}' - 从
traceparentheader 提取 trace_id：先按-分割，取第1段，再确认长度是32位，不足补零，别直接切片 - 如果日志系统要求
trace_id必须是 UUID 格式（如某些 APM），别强转，老实用原始字符串，否则会被截断或校验失败
复杂点在于：trace_id 的生命周期管理、跨线程/协程边界、与 OpenTelemetry SDK 的耦合度，这些地方一松动，日志里就只剩时间戳和 level 了。
