OpenTelemetry SDK 详解：Resource、Provider 与三大信号

OpenTelemetry SDK 是 OTel API 的官方实现，负责把埋点调用变成真正的遥测数据：管理 Resource 身份、执行采样决策、聚合指标、批量导出到 Collector 或后端——API 面向埋点代码，SDK 面向运行配置，理解 SDK 的组件模型是把 OTel 用好的关键。

核心要点速览

• Resource 描述「数据是谁产生的」（service.name、版本、主机），是所有遥测数据的身份；
• TracerProvider/MeterProvider/LoggerProvider 分别是链路、指标、日志信号的入口工厂；
• Span Processor 决定 Span 如何被加工导出（生产用 Batch，调试用 Simple）；
• 绝大多数场景用自动埋点 + 环境变量配置即可，不必手写 SDK 初始化。

Resource：数据的身份

Resource 是一组描述遥测数据来源的属性集合（service.name、service.version、deployment.environment、host.name 等），附着在 SDK 产出的所有数据上。service.name 是观测云 APM 中服务识别的关键字段，务必显式设置而非用默认值。

TracerProvider 与 Span 流水线

链路信号的路径：

1. Tracer 由 TracerProvider 创建，用于生成 Span；
2. Span 结束后进入 Span Processor 链：SimpleSpanProcessor（立即导出，仅调试用）或 BatchSpanProcessor（攒批导出，生产标配）；
3. 最终由 Exporter（OTLP gRPC/HTTP）发出。

采样在 Span 创建时决策：头部采样（parentbased_traceidratio 最常用）或基于规则的采样，详见《OpenTelemetry 采样详解》。

Context Propagation：跨服务串联

SDK 通过 Propagator 在出/入站请求中注入与提取上下文（默认 W3C traceparent），保证跨服务链路不断。细节见《OpenTelemetry 上下文传播》。

MeterProvider 与指标工具

指标侧的核心概念：

• Instruments：Counter（单调累加）、UpDownCounter（可加可减）、Histogram（分布）、Observable Gauge（回调读取）；
• Reader：周期性拉取（如 Prometheus）或推送（OTLP）聚合结果；
• View：对聚合方式、保留属性做定制的规则。

选择建议见《OpenTelemetry 指标详解》。

自动埋点 vs 手动埋点

• 自动埋点：Java Agent、Python agent 等零代码方案，覆盖主流框架/库，先跑起来；
• 手动埋点：用 API 为关键业务方法补 Span 与自定义指标，补齐业务语义。

推荐路径：自动埋点打底 → 核心业务链路手动增强。

观测云落地：SDK 侧只需三个环境变量

export OTEL_SERVICE_NAME=order-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:4318
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Token <观测云Token>"
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.2   # 采样 20%

配置完成后：链路出现在观测云 APM 的服务列表与链路检索中；指标进入指标模块；日志（如开启）进入日志查看器并自动关联 trace_id。

常见问题（FAQ）

Q：API 和 SDK 为什么要分开？ 库开发者只依赖 API 写埋点（零实现成本），应用开发者在启动时装配 SDK——这样第三方库的埋点在所有应用中都能生效。

Q：多个信号能用同一个 Exporter 吗？ 可以，OTLP exporter 支持 traces/metrics/logs 三种信号共用端点，也可通过 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等分信号覆盖。

Q：Batch 导出会丢数据吗？ 进程崩溃时缓冲区中未导出的数据会丢。配置合理的队列容量与导出间隔，并保证应用优雅退出时调用 shutdown/flush。

Q：SDK 初始化失败如何排查？ 开启 SDK 内部日志（如 OTEL_LOG_LEVEL=debug），检查端点连通性与 Token 有效性；观测云侧可在 DataKit 日志中查看 OTLP 接收情况。

系列阅读

• 上一篇：《OTLP 协议详解》
• 下一篇：《OpenTelemetry 语义约定》
• 相关：《什么是 OpenTelemetry》 · 《OpenTelemetry 最佳实践》 · 《返回索引》