可观测性与稳定性 / 系统课时
设计 Receiver 到 Exporter 的 Pipeline
设计 Receiver 到 Exporter 的 Pipeline
本篇把 Collector 配置拆成可验证的数据流:先定义 Receiver、Processor 与 Exporter,再按 traces、metrics、logs 三类信号建立独立 Pipeline,最后用配置校验和一条 OTLP/HTTP Trace 请求确认输入确实到达导出端。
学习目标
- 说明组件“已配置”与“已加入 Pipeline”之间的区别。
- 为 traces、metrics、logs 分别连接 Receiver、Processor 与 Exporter。
- 用
validate、OTLP/HTTP 请求和debugExporter 验证链路。
先把组件定义与 Pipeline 连接分开
Collector 顶层的 receivers、processors、exporters 只是在声明组件实例;真正启用组件的是 service.pipelines。每条 Pipeline 只处理一种信号,名称可以是 traces、metrics、logs,也可以使用 traces/primary 这类 type/name 形式创建同类型的多条管道。
Pipeline 中的顺序也有语义:数据从 Receiver 进入,按 processors 列表顺序处理,再交给一个或多个 Exporter。同一个组件配置可以被多条 Pipeline 引用;Processor 被多条 Pipeline 引用时,各 Pipeline 会获得独立实例,因此不要把它理解成跨信号共享的一段可变缓冲区。

用一个配置建立三条信号管道
下面的主示例只使用 Collector 核心常见组件,debug Exporter 便于本地观察,不依赖真实后端。保存为 otelcol.yaml:
receivers:
otlp:
protocols:
grpc:
endpoint: 127.0.0.1:4317
http:
endpoint: 127.0.0.1:4318
processors:
batch:
# 先按数量触发发送,同时用超时避免低流量长期滞留。
send_batch_size: 512
timeout: 1s
exporters:
debug:
# detailed 便于在本地确认实际收到的资源和 Span。
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [debug]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [debug]
logs:
receivers: [otlp]
processors: [batch]
exporters: [debug]这份配置的关键不是“定义了三个组件”,而是三个信号 Pipeline 都显式引用了它们。OTLP Receiver 会按请求端点和信号类型把数据送入对应 Pipeline;batch 在每条管道内独立工作;debug 只是当前出口,生产环境可以替换或并列增加 OTLP、Kafka 等实际 Exporter。
验证配置与真实输入
先让 Collector 只解析并校验配置,二进制名称如果是 otelcol-contrib,替换下面的 otelcol 即可:
otelcol validate --config=otelcol.yaml预期结果:命令以退出码 0 结束,并且不出现 invalid configuration、未知组件或 Pipeline 引用错误。不同版本可能没有额外成功文本,因此不要依赖某一条固定日志。
随后启动 Collector:
otelcol --config=otelcol.yaml预期结果:进程保持前台运行,OTLP gRPC 与 HTTP Receiver 成功监听 127.0.0.1:4317 和 127.0.0.1:4318;具体启动日志中的时间与字段格式可能不同。
另开终端发送一条符合 OTLP/JSON 的 Trace:
# 构造一条最小 OTLP/JSON Trace。
cat > trace.json <<'JSON'
{
"resourceSpans": [{
"resource": {"attributes": [{
"key": "service.name",
"value": {"stringValue": "pipeline-demo"}
}]},
"scopeSpans": [{
"scope": {"name": "manual-check"},
"spans": [{
"traceId": "5B8EFFF798038103D269B633813FC60C",
"spanId": "EEE19B7EC3C1B174",
"name": "pipeline-check",
"startTimeUnixNano": "1544712660000000000",
"endTimeUnixNano": "1544712661000000000"
}]
}]
}]
}
JSON
# 输出 HTTP 状态码,再读取 OTLP 响应体。
curl -sS -o response.json -w '%{http_code}\n' \
-H 'Content-Type: application/json' \
--data-binary @trace.json \
http://127.0.0.1:4318/v1/traces
cat response.json预期输出:
200
{}同时,Collector 的 debug Exporter 应记录 1 条名为 pipeline-check 的 Span,并能看到资源属性 service.name=pipeline-demo;日志时间戳和排版随版本变化。这个验证证明 Trace 输入走通了 otlp → batch → debug,而不是仅证明 YAML 能被解析。
设计 Pipeline 时守住信号边界
traces、metrics、logs 可以共用同一个 OTLP Receiver 配置,却不会因为“共用 Receiver”而混成一条数据流。需要不同处理策略时,应创建独立的组件实例,例如 batch/traces 与 batch/logs,再分别引用;需要同一信号走不同目的地时,则可以创建 traces/primary、traces/audit 等多条 Pipeline。
生产配置的验收至少要同时回答三个问题:数据从哪个 Receiver 进入、按什么顺序经过哪些 Processor、最终交给哪些 Exporter。只要这三点能从 service.pipelines 直接读出来,Pipeline 才算具备可维护性。