每一份 Collector 配置都是一个遵循同样几条规则的 YAML 文档。把这些规则学一次,你就能读懂任何 Collector 配置,包括随 Helm chart 和 Operator 一起发布的那些。本指南涵盖结构、命名方案、组件如何被打开、如何拆分和合并文件,以及如何注入环境变量。

五种组件类型

配置段	作用	示例
receivers	接收数据	otlp、prometheus、filelog、hostmetrics
processors	转换、过滤、丰富、批处理	batch、memory_limiter、k8s_attributes、tail_sampling
exporters	发送数据	otlp、otlphttp、debug、prometheus
connectors	连接两条管线,在一条中充当 exporter,在另一条中充当 receiver	spanmetrics、forward、routing
extensions	在管线旁边增加能力	health_check、zpages、file_storage、认证扩展

还有第六个配置段 service,把它们连接在一起。

组件在 service 启用它们之前是关闭的

这是最常见的困惑来源。配置一个 receiver 并不会打开它。组件只有在 service 中的某个管线引用它时才会生效:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  debug:
  otlp_grpc:
    endpoint: gateway.example.com:4317

service:
  extensions: [health_check, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc]
    metrics:
      receivers: [otlp]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      exporters: [otlp_grpc]

已定义但从未被引用的组件会被忽略,这对于在文件中保留多种变体很有用,但当什么都没有到达时很容易被忘记。管线以 traces、metrics 和 logs 命名,receiver、processor 或 exporter 必须支持它所加入的管线的信号类型。

命名:type 和 type/name

组件标识符是它的类型,后面可选地跟着 /name。当你需要多次配置同一种组件类型时,使用名称:

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  otlp/vendor:
    endpoint: otlp.vendor.example.com:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/tempo, otlp/vendor]   # fan out to two backends

每个标识符必须唯一。上面的扇出把每个 span 都发送到两个目的地。

管线详解

• processor 的顺序很重要。 数据按列出的顺序依次通过 processor。把 memory_limiter 放在最前,把 batch 放在最后(参见弹性指南)。
• 一个组件可以出现在多条管线中。 每条使用某个 processor 的管线都会获得它自己的实例。
• Connector 连接管线。 connector 作为一条管线的 exporter,以及另一条管线的 receiver 被列出。例如,spanmetrics 把 span 变成指标:

connectors:
  spanmetrics:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/tempo, spanmetrics]
    metrics:
      receivers: [otlp, spanmetrics]
      processors: [batch]
      exporters: [otlphttp/prometheus]

环境变量

在任何需要值的地方使用 ${env:NAME},并用 :- 提供类 bash 风格的默认值:

exporters:
  otlp:
    endpoint: ${env:OTLP_ENDPOINT:-gateway.example.com:4317}
    headers:
      authorization: Bearer ${env:API_TOKEN}

要写字面的美元符号,请使用 $$。因为密钥通过环境变量传入,文件本身不含密钥,可以被提交。

配置来源与合并文件

--config 接受路径,或者形如 scheme:value 的 URI,支持的 scheme 有 file、env、yaml、http 和 https:

otelcol --config=file:/etc/otelcol/base.yaml --config=file:/etc/otelcol/overrides.yaml
otelcol --config=env:MY_CONFIG_IN_AN_ENVVAR
otelcol --config="yaml:exporters::debug::verbosity: normal"

当你传入多个 --config 选项时,Collector 会把它们合并成一份配置。每个文件可以是不完整的,但合并后的结果必须是完整的,因为 Collector 不会替你添加组件。用它来保留一个共享的基础文件和一个小型的每环境覆盖文件。

你也可以将另一个文件嵌入到某个值中:

exporters: ${file:exporters.yaml}

http 和 https provider 从 URL 加载配置,这很方便,但意味着 Collector 的行为取决于那台服务器,所以请有意识地使用它们。

验证

otelcol validate --config=config.yaml
# or with the contrib image
docker run --rm -v $(pwd)/config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

validate 能捕获未知组件、语法错误,以及引用了你没有定义之物的管线。它不能证明后端是可达的。

需要了解的安全默认值

Receiver 默认绑定到 localhost。当所有发送方都运行在同一主机上时,这是安全的,但它意味着容器中的 Collector 在你设置诸如 0.0.0.0:4317 之类的端点之前,是无法从外部访问的。当你把端点开放给网络时,请添加 TLS 和认证(参见后端指南),并用网络策略或防火墙规则限制访问。

真实项目的可读布局

collector/
├── base.yaml            # receivers, processors, shared pipelines
├── env/
│   ├── dev.yaml         # exporters and endpoints for dev
│   └── prod.yaml
└── README.md

用 --config=file:base.yaml --config=file:env/prod.yaml 运行它。审阅者可以确切地看到每个环境有什么变化。

快速参考

• 在顶部定义组件,在 service 中启用它们。
• 使用 type/name 来重复某种组件类型。
• 有意识地为 processor 排序。
• 对于任何特定于环境或机密的内容,使用 ${env:VAR}。
• 合并多个 --config 文件,并在 CI 中运行 validate。