Python OpenTelemetry 的全链路埋点规范

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 起才稳定。