可观测性与稳定性 / 系统课时

设计 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 请求和 debug Exporter 验证链路。

先把组件定义与 Pipeline 连接分开

Collector 顶层的 receivers、processors、exporters 只是在声明组件实例;真正启用组件的是 service.pipelines。每条 Pipeline 只处理一种信号,名称可以是 traces、metrics、logs,也可以使用 traces/primary 这类 type/name 形式创建同类型的多条管道。

Pipeline 中的顺序也有语义:数据从 Receiver 进入,按 processors 列表顺序处理,再交给一个或多个 Exporter。同一个组件配置可以被多条 Pipeline 引用;Processor 被多条 Pipeline 引用时,各 Pipeline 会获得独立实例,因此不要把它理解成跨信号共享的一段可变缓冲区。

三类信号从 Receiver 经 Pipeline 到 Exporter 的数据流

用一个配置建立三条信号管道

下面的主示例只使用 Collector 核心常见组件,debug Exporter 便于本地观察,不依赖真实后端。保存为 otelcol.yaml:

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 即可:

bash
otelcol validate --config=otelcol.yaml

预期结果:命令以退出码 0 结束,并且不出现 invalid configuration、未知组件或 Pipeline 引用错误。不同版本可能没有额外成功文本,因此不要依赖某一条固定日志。

随后启动 Collector:

bash
otelcol --config=otelcol.yaml

预期结果:进程保持前台运行,OTLP gRPC 与 HTTP Receiver 成功监听 127.0.0.1:4317 和 127.0.0.1:4318;具体启动日志中的时间与字段格式可能不同。

另开终端发送一条符合 OTLP/JSON 的 Trace:

bash
# 构造一条最小 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

预期输出:

text
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 才算具备可维护性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 Receiver 到 Exporter 的 Pipeline

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通