OpenTelemetry OpenTelemetry

OpenTelemetry 详解:SDK、OTLP 与 Collector

在编写任何 YAML 之前,先了解各个活动部件以及配置所在的三个位置。

8 min 初级

OpenTelemetry 有许多部分,大多数困惑来自把它们搞混。本指南把它们分开:什么运行在你的应用内部、什么运行在它旁边,以及每一个在哪里配置。一旦地图清楚了,本系列的其余部分大多就是填写 YAML。

它解决的问题

在 OpenTelemetry 之前,每个监控厂商都提供自己的 agent 和自己的数据格式。更换厂商意味着重新插桩每个服务,而同时运行两个工具意味着运行两个 agent。OpenTelemetry 把这两个关注点分开:插桩只产生一次标准数据,管线决定它去往何处。

各个部分

部分它是什么在哪里运行
API插桩代码调用的接口(开始一个 span、记录一个指标)在你的应用中
SDKAPI 背后的实现:采样、批处理、导出在你的应用中
Instrumentation(插桩)为库(HTTP、数据库)创建遥测数据的代码在你的应用中,通过库或零代码 agent
OTLP遥测数据的传输协议,基于 gRPC 或 HTTP在组件之间
Collector一个接收、处理并导出遥测数据的独立服务在应用旁边、每个节点,或作为集中的网关
Semantic conventions(语义约定)属性的标准名称,例如 http.request.method无处不在

应用可以直接导出到后端,但通常的建议是在中间放一个 Collector,因为它让你无需重新部署应用就能更改处理方式和目的地。

三层配置

  1. 应用的 SDK,用 OTEL_* 环境变量配置,或者越来越多地用 OTEL_CONFIG_FILE 所指向的声明式 YAML 文件配置。它控制服务名称、资源属性、采样器,以及导出到哪里。
  2. Collector,用 YAML 文件配置。它控制接收什么、如何转换数据,以及数据去往何处。
  3. 平台粘合层:Docker Compose 文件、Helm values,或来自 OpenTelemetry Operator 的 Kubernetes 资源,它们部署 Collector 并向应用注入配置。

这些层中的一切都是文本,所以它可以放在 Git 中。

一张图看数据流

┌────────────┐  OTLP   ┌─────────────────────────────┐        ┌───────────┐
│ App + SDK  │────────▶│ Collector                   │───────▶│ Traces    │
│ (env vars  │ 4317/   │ receivers → processors →    │───────▶│ Metrics   │
│  or YAML)  │ 4318    │ exporters (config.yaml)     │───────▶│ Logs      │
└────────────┘         └─────────────────────────────┘        └───────────┘

一览各种信号

  • Traces(追踪) 将请求在各服务之间的路径记录为 span。它们回答”时间花在哪里了?”
  • Metrics(指标) 是随时间变化的数值度量,例如请求计数和延迟直方图。它们回答”系统的趋势如何?”
  • Logs(日志) 是带时间戳的记录。OpenTelemetry 可以将它们与追踪关联,所以一行日志会链接到产生它的 span。

每种信号在 Collector 中都有自己的管线,在 SDK 中也有自己的 provider。

稳定性:采用之前先读

OpenTelemetry 很庞大,它的各个部分成熟的速度各不相同。OTLP 协议以及追踪和指标 API 是稳定的。Collector 组件各自带有自己的稳定性级别,许多 contrib 组件仍是 beta 或 alpha。声明式 SDK 配置在 2026 年达到了稳定的 schema,但 SDK 的实现跟进得并不均衡,Java 和其他几个走在前面。当你选择某个组件或某个功能时,请在文档中检查它的稳定性,并固定版本。

通过本系列的建议路径

  1. 运行一个 Collector 并向它发送数据(Docker Compose)。
  2. 了解 Collector 的配置模型。
  3. 用环境变量,以及在支持的地方用声明式文件,配置 SDK。
  4. 为应用添加零代码插桩。
  5. 让 Collector 达到生产就绪:批处理、内存限制、重试、采样。
  6. 用 Helm 或 Operator 将它部署到 Kubernetes。
  7. 收集日志和基础设施指标,安全地发送到后端,并排查问题。

参考资料请见 OpenTelemetry 文档。

热门指南