OTLP

OTLP（OpenTelemetry Protocol）是 OpenTelemetry 项目定义的遥测数据传输协议，用来规定应用、代理、OpenTelemetry Collector 和可观测性后端之间如何编码、发送和确认日志、指标、链路追踪与性能剖析数据。

核心问题

没有 OTLP 时，每个 SDK、Agent 和后端都可能定义自己的上报格式：A 语言 SDK 发一种 JSON，B 语言 SDK 发另一种二进制格式，Collector 又要为每个后端写专用接收逻辑。这样会带来三类问题：

跨语言不稳定：同一条 span、metric 或 log record 在不同语言里字段名和类型不一致。
中间节点难复用：Agent 或 Collector 很难统一接收、批处理、采样、脱敏和转发。
厂商绑定强：应用一旦使用某个后端私有协议，迁移或同时发送给多个后端的成本很高。

OTLP 解决的是“可观测性数据在网络上如何以标准方式交付”的问题。它不是数据库、不是查询语言，也不决定业务应该采集哪些字段；它只定义遥测数据的 wire-level 交付边界。

核心对象

对象	作用	工程关注点
Telemetry source	产生遥测的应用、SDK、Agent 或 Collector	批量大小、flush 周期、资源属性
OTLP exporter	把内存中的遥测数据编码成 OTLP 请求并发送	endpoint、protocol、headers、timeout、retry
OTLP receiver	接收 OTLP 请求的服务端组件	监听端口、TLS、鉴权、最大请求大小
Export request	按信号类型发送的请求体	traces、metrics、logs、profiles 使用各自的 service request
Resource	描述数据来自哪个服务、主机、容器或设备	`service.name`、版本、实例 ID 等稳定属性
Scope	描述产生数据的 instrumentation scope	SDK 名称、库名、版本
Signal payload	具体的 span、metric、log record 或 profile	字段语义、时间戳、属性基数
Export response	服务端对本批数据的确认	成功、失败、部分成功、是否应重试

核心机制

1. 数据先变成 OpenTelemetry 数据模型

应用内部先通过 OpenTelemetry SDK 生成遥测对象。典型层级是：

Resource
  -> InstrumentationScope
    -> Signal data

例如 trace 数据可以理解为：

ResourceSpans
  -> ScopeSpans
    -> Span[]

这里 Resource 表示“谁产生了数据”，例如服务名、版本、容器或设备；Scope 表示“哪段 instrumentation 代码产生了数据”；Span[] 才是具体请求片段。metrics、logs、profiles 也采用类似的资源 + scope + signal 数据分层。

2. Exporter 把数据编码成 Protobuf 消息

OTLP 的核心 schema 定义在 Protocol Buffers .proto 文件中。发送方不会把语言里的对象原样塞到网络里，而是按 schema 编码成稳定的 Wire Format。

最小流程是：

SDK data
  -> batch
  -> Export*ServiceRequest protobuf message
  -> OTLP/gRPC or OTLP/HTTP request
  -> Collector/backend
  -> Export*ServiceResponse

Export*ServiceRequest 里的 * 代表信号类型，例如 traces、metrics、logs 或 profiles。它不是一个通用“任意 JSON blob”，而是每类信号有明确字段结构的 protobuf message。

3. 传输有 gRPC 和 HTTP 两条主路径

OTLP 常见传输方式有两类：

方式	默认端口	请求形态	适用直觉
OTLP/gRPC	`4317`	gRPC unary request/response，protobuf payload	服务间长连接、高吞吐、云原生 Collector 到 Collector
OTLP/HTTP	`4318`	HTTP `POST`，protobuf 或 JSON payload	简单网络环境、代理友好、直接 curl/debug 更方便

OTLP/gRPC 建立底层 gRPC 连接后，客户端持续发送 unary export 请求，每个请求对应一个响应。OTLP/HTTP 则用 POST 把一批遥测发送到信号专用路径：

/v1/traces
/v1/metrics
/v1/logs
/v1/profiles

无论走 OTLP/gRPC 还是 OTLP/HTTP，protobuf schema 是同一套；差别主要在 transport、content type、endpoint 拼接、代理兼容性和运维配置。

4. 响应只说明“本批是否被接收”

OTLP 是 request/response 风格协议。服务端响应可以表达：

本批数据已接收。
请求不合法或服务不可用。
部分数据被接收，部分数据被拒绝或丢弃。
客户端应根据错误类型、状态码或 retry 策略稍后重试。

这意味着 OTLP 的“成功”不是业务成功，也不是数据已经可在 dashboard 查询到。它只说明接收端按协议处理了这一批 export 请求；后续 pipeline、存储、索引、采样和保留策略仍可能影响最终可见性。

5. 常见配置入口

OTLP exporter 常用环境变量包括：

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer xxx
OTEL_EXPORTER_OTLP_TIMEOUT=10000

也可以按信号拆开配置：

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://collector:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://collector:4318/v1/logs

注意：使用总的 OTEL_EXPORTER_OTLP_ENDPOINT 时，OTLP/HTTP exporter 通常会自动拼接 /v1/traces、/v1/metrics、/v1/logs 等信号路径；使用信号专用 endpoint 时，路径通常要写完整。

工程用途

统一接入：应用 SDK、Agent、Grafana Alloy、Collector 和后端可以围绕同一传输协议互操作。
边缘或设备遥测：设备端可以把 bounded health、metrics、logs 摘要或 traces 发到本地 Collector，再由 Collector 做缓冲和转发。
厂商解耦：应用只需要向 OTLP endpoint export，后端可以从 APM、日志系统或时序库之间迁移。
管道化处理：Collector 可以在 OTLP 入口后做 batch、resource detection、采样、过滤、脱敏和多后端 fan-out。
调试上报链路：通过端口、路径、status code、Collector 日志和 export 失败计数定位是应用没发、Collector 没收，还是后端没存。

观察 OTLP 链路时，重点看 export 成功率、重试次数、drop 数、queue 长度、batch 大小、请求延迟、接收端拒绝原因和 Label Cardinality。

边界与常见坑

OTLP 不是 OpenTelemetry 本身：OpenTelemetry 还包括 API、SDK、语义约定和 Collector；OTLP 只是遥测数据交付协议。
OTLP 不是存储或查询协议：它负责 ingest，不负责像 Prometheus、Loki 或 Grafana 那样存储、查询和展示。
端口和协议不要混用：4317 通常是 OTLP/gRPC，4318 通常是 OTLP/HTTP。把 HTTP exporter 指到 gRPC 端口，常见现象是连接成功但协议解析失败，或直接收到 404/415/connection reset。
HTTP endpoint 路径要分清：OTLP/HTTP 的总 endpoint 和信号专用 endpoint 行为不同；专用 endpoint 常要包含 /v1/traces 等完整路径。
protobuf schema 不等于语义正确：字段能编码成功，不代表 service.name、span 属性、metric temporality 或 log severity 语义正确。
鉴权和加密不是协议自动保证：生产环境应使用 HTTPS/TLS、mTLS 或明确的认证 header；OTLP 本身不会证明发送方身份或数据可信。
不要把自由文本塞进高基数字段：OTLP 能传属性，但标签或 attribute 设计失控会让后端成本和查询复杂度快速上升。
profile 信号成熟度要单独确认：截至 2026-06，OTLP 的 traces、metrics、logs 为稳定信号，profiles 仍处于 development 状态。

Sean's Blog

探索