OpenTelemetry Python trace丢失主因是上下文未传递：需显式配置propagator、ASGI框架须装opentelemetry-instrumentation-asgi、async场景要避免手动context操作、采样策略须统一版本并分层设置。
OpenTelemetry Python 中 trace 丢失的常见原因
Python 服务里 trace_id 突然变空、下游收不到 span，大概率不是 SDK 没装好，而是上下文没传进去。
OpenTelemetry 的 Python SDK 默认不自动注入/提取 HTTP 请求头（比如 traceparent），必须显式配置 propagator；同时，异步框架（如 FastAPI、Starlette）需额外安装 opentelemetry-instrumentation-asgi，否则中间件根本不会调用 extract。
- 检查是否调用过
set_global_textmap，并传入TraceContextTextMapPropagator() - 用
curl -H 'traceparent: 00-12345678901234567890123456789012-1234567890123456-01' http://localhost:8000/api手动验证 header 是否被识别 - FastAPI 项目必须在
app = FastAPI()后立即加Instrumentor().instrument_app(app)，仅instrument()全局钩子对 ASGI 不生效
Span 命名混乱导致查询困难
Span 名写成 "request" 或 "handle" 这类泛化名称，等于埋点白做——在 Jaeger 或 Grafana Tempo 里根本没法按业务维度过滤或聚合。
命名必须体现「资源 + 动作」，且保持跨服务一致。比如用户服务查 ID 是 "user.get_by_id"，订单服务调它也得用同样 name，不能写成 "fetch_user" 或 "get_user"。
立即学习“Python免费学习笔记（深入）”；
- HTTP handler 推荐用
method + route：如"GET /api/v1/users/{id}"（注意别带实际 ID 值，避免 cardinality 爆炸） - 数据库操作用
db + operation + table：如"db.select.users"、"db.update.orders" - 避免在 span name 里拼接变量，改用
set_attribute("user.id", user_id)记录高基数字段
async/await 场景下 context 丢失的典型表现
用 async def 写的函数里，span 看起来创建了，但所有子 span 都挂在 root 上、时间线错乱、甚至 current_span() 返回 None——这是 asyncio contextvars 隔离导致的。
OpenTelemetry Python 1.20+ 已默认支持 async context，但前提是不能手动用 context.attach() 或混用 threading.local 风格的旧逻辑；同时，第三方库（如 aiohttp、httpx）必须使用对应 instrumentation 包。
- 禁用
Tracer.start_span()的start_time手动传参，它会绕过 context 自动绑定 - 确认已安装
opentelemetry-instrumentation-aiohttp-client（而非 requests 版本） - 自定义异步工具函数时，用
with tracer.start_as_current_span("xxx") as span:，别用start_span().add_event()分两步
采样策略配置不当引发数据失真
线上全量上报 span，结果后端压垮、存储暴涨、关键链路反而被淹没——这不是 OpenTelemetry 本身的问题，是采样没设对。
默认的 ParentBased(AlwaysOn) 在入口服务（如 API 网关）开启即可，下游应切换为 ParentBased(TraceIdRatioBased(0.1))，既保链路完整，又控量。
- 网关层设
AlwaysOn，确保每个请求至少有一个 trace；内部服务统一用TraceIdRatioBased(0.05) - 不要对 error span 单独设
AlwaysOn，OpenTelemetry 的ParentBased默认已包含 error 透传逻辑 - 本地调试时可临时用
AlwaysOn，但必须通过环境变量控制，禁止硬编码进TracerProvider
最常被忽略的是：不同服务用了不同版本的 OTel Python SDK，低版本不支持 TraceIdRatioBased 的 seed 行为，会导致同一 trace 在上下游采样结果不一致——务必统一 SDK 版本，至少 1.22.0 起才稳定。
