## 31｜OpenTelemetry 与 Python 全链路可观测：指标、日志、追踪三位一体

31｜OpenTelemetry 与 Python 全链路可观测：指标、日志、追踪三位一体

专栏定位：Python 工程化进阶（第31章）
适读人群：后端工程师、SRE、可观测平台与基础设施方向同学

摘要

当单体拆成微服务、同步调用叠上异步任务之后，「谁慢、为什么慢、影响多少用户」往往说不清。
OpenTelemetry（OTel）提供了一套厂商中立的标准：同一套上下文（Context）贯穿 Traces、Metrics、Logs，让 Python 服务能接入 Jaeger、Tempo、Prometheus、Grafana 等生态而不被绑定。
本章从工程落地角度，讲清 SDK 接入顺序、自动/手动埋点、采样策略、成本控制，以及如何把现有logging与追踪 ID 对齐，避免「三套系统三套口径」的灾难。

SEO 摘要

系统讲解 Python 服务基于 OpenTelemetry 的可观测体系建设，涵盖 Tracer、Meter、日志关联、采样与后端选型，适合中大型分布式后端与平台团队落地全链路追踪与统一指标。

目录

• 可观测性三支柱与常见踩坑
• OpenTelemetry 在 Python 中的组件分工
• 接入顺序建议：先追踪上下文，再指标，再日志关联
• 代码示例：FastAPI 最小接入
• 采样、成本与Cardinality治理
• 架构权衡对比表（A/B/C）
• 可执行实验步骤
• 发布后7天观察指标模板
• 案例复盘（×2）
• 术语注释与面试高频问答
• 版权声明

可观测性三支柱与常见踩坑

**指标（Metrics）**回答「系统是否在健康区间」：QPS、错误率、延迟分位数、队列深度。
**日志（Logs）**回答「某次请求里发生了什么事件」。
**追踪（Traces）**回答「一次用户请求跨了多少服务、每段耗时多少」。

常见踩坑包括：只上指标没有追踪，排障仍靠猜；只上追踪没有采样，存储成本爆炸；日志不带trace_id，三支柱无法关联。
Python 生态里还有 GIL、异步与线程混用导致的上下文丢失问题，必须在中间件层统一注入与传播。

OpenTelemetry 在 Python 中的组件分工

• API：定义 Span、Meter 等抽象，业务代码尽量只依赖 API。
• SDK：具体实现、导出器、批处理、采样器。
• Instrumentation：对 FastAPI、requests、SQLAlchemy 等的自动埋点包。
• Exporter：OTLP（推荐）、Jaeger、Prometheus 等。

生产环境建议：先锁定导出协议（通常 OTLP gRPC/HTTP），再选后端；避免每个团队各写一套导出配置。

接入顺序建议

1. W3C Trace Context 传播：确保网关到 Python 服务到下游 HTTP/gRPC 头一致。
2. 框架中间件：在 ASGI/WSGI 入口创建 Root Span，填充http.route、http.status_code。
3. 业务 Span：对关键业务步骤（下单、支付回调）手动start_as_current_span。
4. Metrics：对饱和度类指标（连接池、队列）用 Observable Gauge。
5. Logs：日志 formatter 注入trace_id/span_id（或 OTLP Logs）。

代码示例：FastAPI 最小接入（示意）

fromfastapiimportFastAPIfromopentelemetryimporttracefromopentelemetry.sdk