OTLP 协议详解:OpenTelemetry 的数据传输标准

OTLP(OpenTelemetry Protocol)基于 Protobuf 定义遥测数据,支持 gRPC 与 HTTP。本文讲解数据模型、传输与重试语义,以及如何配置导出到观测云 DataKit。

最佳实践
应用性能监控中的服务链路与指标示意

OTLP(OpenTelemetry Protocol)是 OpenTelemetry 原生的遥测数据传输协议,用 Protobuf 定义数据结构,支持 gRPC(默认 4317 端口)与 HTTP(默认 4318 端口)。 OTLP 对链路、指标和日志的传输规范已稳定,Profiles 仍处于开发中。发送端和接收端支持同一种信号、传输方式及编码时,可通过同一套协议交换数据。

核心要点速览

  • OTLP 定义数据如何编码与传输,数据入库与查询由后端处理。
  • gRPC 使用二进制 Protobuf,HTTP 支持二进制 Protobuf 或 OTLP 的 JSON 映射,配置以接收端的实际支持为准。
  • 数据按 Resource(哪个资源产生)→ Scope(哪个埋点组件产生)→ 具体信号记录组织。
  • DataKit 接收链路、指标与日志的 OTLP 数据。其 HTTP 端口默认是 9529,路径使用 /otel/v1/ 前缀。

OTLP 的工作机制

一次 OTLP 传输包含三个阶段:

  1. 数据收集。SDK 或采集端把遥测数据按 OTLP 数据模型组织成导出请求。
  2. 传输。通过 gRPC 一元调用或 HTTP POST 发送。发送端与接收端可配置 gzip、TLS 与接收端要求的鉴权信息。
  3. 确认。完整成功表示当前接收端接受了这批数据。规范的 OTLP/HTTP 在完整成功和部分成功时都返回 200。响应中若填充了 partial_success,需检查拒收条数和诊断信息。这个字段也可能只带警告、拒收条数为零。客户端收到这种响应后不得重试原请求。

遇到请求失败时,按协议规定判断是否重试。OTLP/HTTP 将 429、502、503、504 列为可重试的 HTTP 错误码。按 Retry-After 或指数退避重试。其他 4xx 或 5xx 状态码不应重试,例如 400 时应先检查载荷。OTLP/gRPC 则按 gRPC 状态码和相关错误详情处理,例如 UNAVAILABLE 可以重试。

确认只发生在相邻的发送端和接收端之间。Collector 确认接收不代表最终后端已入库。连接中断导致确认丢失时,重发同一批数据还可能产生重复记录。OTLP 规范

OTLP 数据模型

链路、指标和日志共享同样的外层组织方式,下图用 <signal> 表示各信号自己的 Protobuf 字段名。

Export<Signal>ServiceRequest
└── resource_<signal>[]
    ├── resource (service.name, host.name, …)
    └── scope_<signal>[]
        ├── scope (name, version, …)
        └── spans[] / metrics[] / log_records[]

Traces 的 Span 记录含 trace_id、span_id、父 Span 标识、状态与属性等。Metrics 的指标数据可以是 Sum、Gauge、Histogram、ExponentialHistogram 等类型。Logs 的记录包含时间、严重度、内容与属性,也可携带追踪上下文。以链路请求为例,外层字段是 resource_spans 和 scope_spans。如果使用 OTLP/HTTP 的 JSON 编码,字段名要用 lowerCamelCase,例如 traceId,Trace ID 与 Span ID 用十六进制字符串表示,枚举用整数。

gRPC 还是 HTTP?

维度 OTLP/gRPC OTLP/HTTP
标准默认端口 4317 4318
请求与连接 在 gRPC 连接上发一元导出请求 HTTP POST,可复用连接
载荷编码 二进制 Protobuf 二进制 Protobuf 或 OTLP JSON,视接收端支持情况
代理与网关 代理需正确转发 gRPC 代理需允许 POST、路径和内容类型
调试 可用支持相应服务定义的 gRPC 客户端 可用 curl POST 匹配编码的有效载荷

生产环境按 SDK、代理和接收端的支持选择,再测量批量大小、压缩和并发对吞吐及资源消耗的影响。排查 HTTP 接入时,先对照完整路径与 Content-Type,例如二进制 Protobuf 使用 application/x-protobuf。默认路径分别是 /v1/traces、/v1/metrics、/v1/logs,也可能由接收端调整。

服务接入 OTLP 的路径

  1. 应用埋点。用 OTel SDK 或受支持的自动埋点产生遥测数据,按接收端配置导出协议与 endpoint。
  2. 经 Collector 转发。应用先发给 Collector(英文),再按实际管线配置批处理、过滤或脱敏,导出到后端。
  3. 存量格式转换。如果 Collector 发行版包含并启用了对应的 Jaeger 或 Zipkin 接收器,可接收匹配格式的链路数据,再通过 OTLP 导出。需要核对原发送端协议、字段映射和上下文。

选择 DataKit 作为接收端时,先启用 OpenTelemetry 采集器,确认实际监听地址可达,并启用发送端需要的信号。DataKit 的 gRPC 示例监听 127.0.0.1:4317,发送端在其他主机或网络命名空间时需配置可达的接收地址。HTTP 使用 http/protobuf,默认端口是 9529,三种信号分别走 /otel/v1/traces、/otel/v1/metrics、/otel/v1/logs。以下示例适用于默认 HTTP 路由和受信任测试网络中的明文连接,使用前替换主机名。

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:9529/otel

按导出器规范,HTTP 通用 endpoint 是基础 URL,导出器会追加各信号的路径。如果单独设置 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,则填完整 URL,例如 http://datakit-host:9529/otel/v1/traces。指标与日志的专用 endpoint 同理。认证信息按接收端或网关的配置提供,观测云工作空间由实际接入配置决定。

发送一批可辨识的测试数据后,分别核对链路、指标和日志是否在预期工作空间可查。已有 Collector 的过滤和脱敏仍按配置执行。日志与链路关联还需要匹配的 Trace ID 和可查的链路数据。

常见问题(FAQ)

Q:OTLP 有安全性保障吗? 发送端和接收端可配置 TLS。鉴权方式取决于接收端或网关,例如配置要求的鉴权 Header,或者在支持的部署中使用 mTLS。跨不可信网络时应加密并核对服务端证书。

Q:OTLP 会不会成为性能瓶颈? 编码、压缩、网络和接收端处理都有开销。批量和 gzip 可能减少传输开销,也会带来等待、内存或 CPU 成本。可对照发送延迟、队列占用与拒收量调整配置。

Q:老版本 OTLP 和新版本兼容吗? OTLP 利用 Protobuf 的兼容演进机制处理部分字段变化。信号、编码与可选能力仍需两端支持,应按实际 SDK、接收端版本和用到的特性确认。

Q:可以把观测云作为唯一的 OTLP 后端吗? 如果 DataKit 接入覆盖实际需要的信号和处理要求,可以由它将遥测数据送往观测云。应分别核对查询、保留和告警所需的数据。

系列阅读

参考资料:OTLP 规范 · 观测云 OpenTelemetry 接入 · DataKit 文档 · 观测云 APM

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台