trace_id必须在请求入口生成并用contextvar透传，禁止日志格式化时动态生成；推荐secrets.token_hex(16)生成32位十六进制字符串；异步任务需手动传递与恢复，否则链路断裂。
trace_id 必须在请求入口就生成，不能等到日志写入时才造
日志里的 trace_id 不是装饰器或日志格式化器的“补丁项”，它得从最外层请求进来那一刻就确定下来，否则同一次调用里不同模块打的日志会拿到不同的 trace_id，链路就断了。比如 Flask 的 before_request、FastAPI 的依赖函数、或 Django 中间件都是合适的注入点。
常见错误是：在 logging.Formatter.format() 里每次调用都生成一个新 uuid4() —— 这会导致单次请求里每条日志的 trace_id 都不一样。
- 推荐做法：用
contextvars.ContextVar存储当前请求的trace_id，入口处 set，后续所有日志处理器通过%(trace_id)s格式化字段读取 - 不要用线程局部变量（
threading.local），异步框架（如 asyncio）下不生效 - 如果用 structlog，直接绑定到
structlog.contextvars.bind_contextvars(trace_id=...)
trace_id 字符串格式要兼顾可读性、排序性和系统兼容性
很多团队直接用 str(uuid4())，看似省事，但实际埋坑：UUID 是无序的，按字符串排序日志时 trace_id 完全乱序；某些 APM 系统（如 Jaeger）要求 trace_id 是 16 进制、长度为 16 或 32 字节的字符串，而标准 UUID 是 32 位加 4 个短横线，共 36 字符，会被截断或拒收。
- 建议用
secrets.token_hex(16)生成 32 位小写十六进制字符串（如"a1b2c3d4e5f678901234567890abcdef"），满足 Jaeger/Zipkin 要求，也支持字典序时间近似排序 - 避免大小混用（如
token_urlsafe()含-和_），部分日志系统或正则提取规则会出错 - 如果需要带时间戳前缀（如
"20240521-a1b2..."），注意总长别超 128 字符，避免 Kafka 或 ES 字段截断
日志处理器必须透传 contextvar，不能只靠 Formatter
Formatter 只负责把已有字段转成字符串，它本身不参与上下文注入。如果你只改了 Formatter._format，但没让 LogRecord 携带 trace_id，那 %(trace_id)s 就是空或者报 KeyError。
立即学习“Python免费学习笔记（深入）”；
- 正确方式是在自定义
Filter中读取contextvars.ContextVar并赋值给record.trace_id，再在Formatter里引用 - 示例 Filter 片段：
class TraceIdFilter(logging.Filter): def filter(self, record): tid = trace_id_var.get(None) record.trace_id = tid or "none" return True - 别忘了把 Filter 加到 handler 上：
handler.addFilter(TraceIdFilter()) - structlog 用户更简单：用
structlog.stdlib.filter_by_level+structlog.contextvars.merge_contextvars即可自动注入
异步任务（Celery / asyncio.create_task）必须手动传递 trace_id
Python 的 contextvars 不跨协程或子进程自动传播。Celery 任务、asyncio.to_thread()、甚至 multiprocessing 都会丢失原始 trace_id，导致下游日志无法关联。
- Celery：用
task.apply_async(kwargs={"_trace_id": current_trace_id})显式传入，任务函数开头恢复trace_id_var.set(kwargs["_trace_id"]) - asyncio：用
contextvars.copy_context()+ctx.run(...)包裹子任务，或在create_task前手动 set - 子进程场景（如 subprocess.Popen）只能靠环境变量或临时文件中转，且需确保子进程启动后立即读取并 set 到 contextvar
