核心是用contextvars生成并透传trace_id，通过中间件绑定、自定义Formatter注入日志、HTTP Header跨服务传递，确保多线程/协程/跨服务场景下不丢失。
Python 接口日志中做请求链路追踪，核心不是“加日志”，而是让每次请求携带唯一、可传递的上下文标识（如 trace_id），并在所有日志行中自动注入该标识。否则日志散落各处，根本无法关联。
如何生成和透传 trace_id？用 contextvars + 中间件
Python 3.7+ 的 contextvars 是线程安全且支持协程的上下文容器，比旧式 threading.local 更可靠。关键是在请求入口（如 Flask/Werkzeug 或 FastAPI 的中间件）中生成 trace_id 并绑定到当前上下文。
实操建议：
- 用
uuid.uuid4().hex或secrets.token_urlsafe(8)生成短而唯一的trace_id - 在中间件中调用
trace_ctx.set(trace_id)（trace_ctx是预先声明的ContextVar） - 确保中间件注册顺序靠前，早于所有业务逻辑和日志记录
- 异步框架（如 FastAPI）必须用
async def中间件，且contextvars在 async/await 链中天然延续
日志格式里怎么自动塞进 trace_id？自定义 LogRecord 或 Formatter
不能靠手动在每个 logger.info() 里拼接 trace_id——漏写、错位、污染业务代码。正确做法是让日志系统自己从上下文中捞值。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 继承
logging.Formatter，重写format(self, record)方法，在里面调用trace_ctx.get(None)获取当前 trace_id - 把
trace_id注入到record.trace_id属性，再在fmt字符串中用%(trace_id)s引用 - 避免在
format()中抛异常（比如ContextVar未 set 就 get），要用默认值兜底，否则整条日志会丢失 - 如果用 structlog，直接在
wrap_logger或 processor 中加{"trace_id": trace_ctx.get("")}
跨服务调用时 trace_id 怎么透传？HTTP Header + 请求库适配
单服务内有上下文就够了，但调用下游 HTTP 服务（如 requests、httpx）时，trace_id 必须通过 Header 传出去，否则链路就断了。
实操建议：
- 约定 Header 名，如
X-Trace-ID，不要用下划线（部分代理会丢弃） - 对
requests：用 Session 的headers默认值 +before_requesthook（需 monkey patch 或封装工具函数） - 对
httpx：更友好，可用EventHook或自定义Client类，在send()前注入 Header - 下游服务也必须读取该 Header 并重新绑定到自己的
contextvars，否则无法继续向下传 - 别忘了透传
span_id和parent_id（如果要做完整 OpenTracing 兼容）
import logging
import contextvars
from logging import Formatter
trace_ctx = contextvars.ContextVar("trace_id", default="")
class TraceIDFormatter(Formatter):
def format(self, record):
record.trace_id = trace_ctx.get("")
return super().format(record)
handler = logging.StreamHandler()
handler.setFormatter(TraceIDFormatter("[%(trace_id)s] %(asctime)s %(levelname)s %(message)s"))
logging.getLogger().addHandler(handler)
真正难的不是生成一个 ID，而是保证它在多线程、多协程、子进程、HTTP 调用、消息队列（如 Celery）等各种边界场景下不丢失、不混淆。每个透传环节都要显式处理，少一环，链路就断成两截。
