Python SDK 初始化是什么
手动接入 OpenTelemetry 的 Python 应用需要四步：构造 Resource 描述服务身份、创建 TracerProvider 作为埋点入口、挂上导出器把数据送出去、最后把 provider 注册为全局实例。少了任何一步埋点都会静默失效——比如忘记注册全局 provider，代码照样运行，span 却落进默认实现被丢弃，排障时会误以为采集链路的问题。
基本信息
| 适用平台 | Python 3.8 及以上，opentelemetry-sdk 与 exporter 包 |
|---|---|
| 安装方式 | pip 安装 SDK、exporter、instrumentation 三类包 |
| 关键对象 | Resource、TracerProvider、SpanProcessor、SpanExporter |
| 导出方式 | 生产用 BatchSpanProcessor，调试可临时用控制台导出 |
典型使用场景
- 自研框架接入：Web 框架没有现成自动埋点时手动初始化 SDK
- 批量任务观测：定时脚本在启动处初始化 provider，任务结束前刷新数据
- 灰度调试：临时挂控制台导出器，确认属性与字段名是否正确
- 直连采集端：小规模环境跳过 Collector 直接上报到后端
- 统一封装：把初始化逻辑集中到一个模块，避免各服务各写一份
初始化与埋点
初始化与埋点
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
resource = Resource.create({"service.name": "checkout-api"}) # 服务身份
provider = TracerProvider(resource=resource)
provider.add_span_processor( # 批处理导出
BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317", insecure=True)))
trace.set_tracer_provider(provider) # 注册为全局
tracer = trace.get_tracer("checkout") # 之后用它埋点
# 进程退出前：provider.shutdown() 或 force_flush() 刷新缓冲组件与作用
| 组件 | 作用 | 常见问题 |
|---|---|---|
| Resource | 描述服务身份的属性集合 | 少写 service.name 导致检索无入口 |
| TracerProvider | 创建 tracer、管理采样与处理 | 未注册为全局时埋点被丢弃 |
| BatchSpanProcessor | 批量聚合后统一发送 | 不刷新就退出会丢掉缓冲 |
| OTLPSpanExporter | 按 OTLP 协议发送到采集端 | 端点或端口写错时报连接失败 |
| Sampler | 决定哪些链路被保留 | 低采样率下排障样本不足 |
生产环境用 BatchSpanProcessor，它按批发送并降低网络开销；调试期可以临时加一个控制台导出器打印导出内容，但上线前要移除，否则日志会被链路数据淹没。
初始化代码放在应用启动入口执行一次即可；WSGI 或 ASGI 容器里要注意子进程与热重载，避免重复初始化导致重复上报。