Starlette中需在中间件__call__里用secrets.token_urlsafe(8)生成trace_id并存入scope["state"]["trace_id"],下游通过request.scope.get("state", {}).get("trace_id", "unknown")安全读取,日志需用structlog.contextvars绑定,HTTP透传须手动加X-Trace-ID头。

Starlette中间件里怎么生成并注入Trace ID
Starlette本身不内置分布式追踪,但你可以用中间件在请求进入时生成唯一trace_id(比如用uuid4().hex),再挂到scope或state上供后续路由/endpoint访问。关键点是:必须在__call__中处理scope,且不能依赖request.state(因为Request对象在中间件链中可能未被构造)。
常见错误是直接往request.state.trace_id写——此时request还没创建;或者只存到局部变量,下游拿不到。
- 推荐做法:把
trace_id写入scope["state"]["trace_id"],这是Starlette官方支持的跨中间件传递状态的方式 - 若需兼容ASGI规范其他服务器(如Uvicorn、Hypercorn),避免往
scope写自定义键,优先用state子字典 - 生成逻辑建议用
secrets.token_urlsafe(8)替代uuid4,更轻量且足够去重
如何让下游函数(比如API路由)读取Trace ID
在路由函数中,你无法直接拿到scope,但可以通过Request对象间接访问:request.scope["state"].get("trace_id")。注意request.scope是只读视图,但state字典本身可变——前提是中间件已正确初始化它。
容易踩的坑是没做存在性检查就直接取值,导致KeyError或AttributeError。尤其在测试环境绕过中间件时,state可能压根没被设置。
- 安全读法:
request.scope.get("state", {}).get("trace_id", "unknown") - 如果用
Depends封装共用逻辑,可在依赖函数里统一提取并校验trace_id - 不要在
BackgroundTasks或异步子任务里直接用request.scope——它的生命周期只限当前请求上下文
怎么把Trace ID透传到日志和下游HTTP请求
日志里埋trace_id靠structlog或logging.LoggerAdapter最稳;发HTTP请求时,则要手动塞进headers。Starlette不自动透传,这一步必须显式做。
典型疏漏是只在入口加了ID,但调用httpx.AsyncClient或aiohttp时忘了带X-Trace-ID头,导致链路断开。
- 日志建议:用
structlog.contextvars.bind_contextvars(trace_id=...),确保异步任务里也能继承 - HTTP透传:所有出站请求都加
headers={"X-Trace-ID": trace_id},别依赖全局默认头(不可靠) - 如果调用gRPC,需用
grpc.aio.Channel的intercept_channel+MetadataPlugin注入,不是简单加header
为什么用了中间件,日志里还是看不到Trace ID
大概率是日志配置没对接上下文。Starlette中间件设好了trace_id,但Python原生logging不知道该从哪取——它不会自动读scope或contextvars。
另一个高频问题是日志处理器用了多进程(比如RotatingFileHandler配processes=True),而contextvars不跨进程,导致子进程日志丢失ID。
- 解法一(推荐):用
structlog+structlog.contextvars.merge_contextvars,自动合并contextvars里的trace_id - 解法二:自定义
LoggerAdapter,在process()里从request.scope捞ID(仅适用于同步日志场景) - 绝对避免:在日志格式字符串里硬写
%(trace_id)s却不注册LogRecord字段——会报KeyError
Trace ID不是加个中间件就自动全链路生效的,它需要中间件、日志、HTTP客户端、异步任务四者对齐上下文传递方式。最容易被忽略的是异步子任务(比如asyncio.create_task)会丢失contextvars,必须显式用copy_context()捕获并运行。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











