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.name、host.name 等），由各信号 Provider 关联到其产生的数据；多个 Provider 的 Resource 需分别配置一致。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），还需 instrumentation 在边界实际注入/提取，且中间件保留头部；不保证 SDK 单独就完成跨服务传播。细节见《OpenTelemetry 上下文传播》。

MeterProvider 与指标工具

指标侧的核心概念：

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

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

自动埋点 vs 手动埋点

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

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

配置 Exporter 时，还要让 SDK 的协议与接收端一致。下方展示环境变量的写法；其中 4318 与 Token Header 不能直接当作 DataKit 的默认配置，接入观测云前应按 OpenTelemetry 文档确认实际端点、路由和接收端要求。

export OTEL_SERVICE_NAME=order-service
# 示例：已配置的本地 Collector OTLP/HTTP 接收器，不是 DataKit 默认端点
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.2   # 对根链路约20%采样；子Span遵循父级决策，并非所有Span恰好20%

环境变量支持程度依语言SDK/自动配置实现而异，通常初始化时读取，不会自动热更新。先发送一条已知请求，检查服务名、Span 层级和采样结果。指标与日志导出分别验证；需要关联日志时，还应确认日志保留了同一请求的 trace_id。

常见问题（FAQ）

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

Q：多个信号能用同一个 Exporter 吗？ 不同信号使用各自的 exporter 接口/实例，可导出到同一接收端；日志还需相应 bridge/集成，也可通过 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等分信号覆盖。

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

Q：SDK 初始化失败如何排查？ 开启 SDK 内部日志（如 OTEL_LOG_LEVEL=debug），检查端点连通性、协议和接收端实际要求的认证配置；观测云侧可在 DataKit 日志中查看 OTLP 接收情况。

系列阅读

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

[1]: 观测云文档《OpenTelemetry》https://docs.guance.com/integrations/opentelemetry/
[2]: 观测云《APM 平台》https://www.guance.com/product/application-performance-monitoring