OpenTelemetry Collector 配置

了解如何根据需要配置 Collector

你可以根据可观测性需求配置 OpenTelemetry Collector。了解 Collector 配置的工作方式之前,请先熟悉以下内容:

配置位置

默认情况下,Collector 配置位于 /etc/<otel-directory>/config.yaml。<otel-directory> 可以是 otelcol、otelcol-contrib 或其他值,具体取决于 Collector 版本或你使用的发行版。

可以通过 --config 选项提供一个或多个配置。例如:

otelcol --config=customconfig.yaml

--config 标志接受文件路径,也接受 "<scheme>:<opaque_data>" 形式的配置 URI。目前,OpenTelemetry Collector 支持以下 scheme 配置提供程序:

  • file:从文件读取配置,例如 file:path/to/config.yaml。
  • env:从环境变量读取配置,例如 env:MY_CONFIG_IN_AN_ENVVAR。
  • yaml:从 YAML 字符串读取配置,使用 :: 分隔子路径,例如 yaml:exporters::debug::verbosity: detailed。
  • http:从 HTTP URI 读取配置,例如 http://www.example.com。
  • https:从 HTTPS URI 读取配置,例如 https://www.example.com。

也可以使用不同路径下的多个文件提供多个配置。每个文件可以包含完整配置或部分配置,文件之间可以相互引用组件。如果文件合并后无法构成完整配置,用户会收到错误,因为必需组件不会默认添加。可以像下面这样在命令行中传入多个文件路径:

otelcol --config=file:/path/to/first/file --config=file:/path/to/second/file

也可以使用环境变量、HTTP URI 或 YAML 路径提供配置。例如:

otelcol --config=env:MY_CONFIG_IN_AN_ENVVAR --config=https://server/config.yaml
otelcol --config="yaml:exporters::debug::verbosity: normal"

使用 validate 命令验证配置文件。例如:

otelcol validate --config=customconfig.yaml

配置结构

Collector 配置文件的结构包含四类访问遥测数据的流水线组件:

配置每个流水线组件后,必须通过配置文件 service 部分中的流水线启用它。

除流水线组件外,还可以配置 扩展(extensions),为 Collector 添加诊断工具等功能。扩展不要求直接访问遥测数据,也通过 service 部分启用。

下面的 Collector 配置示例包含一个接收器、一个处理器、一个导出器和三个扩展。

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

exporters:
  otlp_grpc:
    endpoint: otelcol:4317
    sending_queue:
      batch:

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

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

注意,接收器、处理器、导出器和流水线通过 type[/name] 格式的组件标识符定义,例如 otlp 或 otlp/2。只要标识符唯一,就可以多次定义同一类型的组件。例如:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  otlp/2:
    protocols:
      grpc:
        endpoint: 0.0.0.0:55690

exporters:
  otlp_grpc:
    endpoint: otelcol:4317
    sending_queue:
      batch:
  otlp_grpc/2:
    endpoint: otelcol2:4317
    sending_queue:
      batch:

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp_grpc]
    traces/2:
      receivers: [otlp/2]
      exporters: [otlp_grpc/2]
    metrics:
      receivers: [otlp]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      exporters: [otlp_grpc]

配置还可以包含其他文件,使 Collector 将它们合并为内存中的单一 YAML 配置表示:

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

exporters: ${file:exporters.yaml}

service:
  extensions: []
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlp_grpc]

其中,exporters.yaml 文件内容为:

otlp_grpc:
  endpoint: otelcol.observability.svc.cluster.local:443

最终在内存中得到的结果为:

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

exporters:
  otlp_grpc:
    endpoint: otelcol.observability.svc.cluster.local:443

service:
  extensions: []
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlp_grpc]

接收器 接收器图标

接收器从一个或多个来源收集遥测数据。它们可以采用拉取方式,也可以采用推送方式,并可能支持一种或多种 数据源。

接收器在 receivers 部分配置。许多接收器提供默认设置,因此只指定接收器名称便足以完成配置。如果需要配置接收器或修改默认配置,可以在这一部分进行。你指定的任何设置都会覆盖已有默认值。

Collector 需要至少一个接收器。下面的示例在同一配置文件中展示了多种接收器:

receivers:
  # Data sources: logs
  fluentforward:
    endpoint: 0.0.0.0:8006

  # Data sources: metrics
  host_metrics:
    scrapers:
      cpu:
      disk:
      filesystem:
      load:
      memory:
      network:
      process:
      processes:
      paging:

  # Data sources: traces
  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      thrift_binary:
      thrift_compact:
      thrift_http:

  # Data sources: traces, metrics, logs
  kafka:
    protocol_version: 2.0.0

  # Data sources: traces, metrics
  opencensus:

  # Data sources: traces, metrics, logs
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: cert.pem
          key_file: cert-key.pem
      http:
        endpoint: 0.0.0.0:4318

  # Data sources: metrics
  prometheus:
    config:
      scrape_configs:
        - job_name: otel-collector
          scrape_interval: 5s
          static_configs:
            - targets: [localhost:8888]

  # Data sources: traces
  zipkin:

处理器 处理器图标

处理器接收接收器收集的数据,在发送给导出器之前对其进行修改或转换。数据处理遵循各处理器定义的规则或设置,可能包括过滤、丢弃、重命名、重新计算遥测数据等操作。流水线中处理器的顺序决定 Collector 对信号执行处理操作的顺序。

处理器是可选的,不过官方 建议使用某些处理器。

可以通过 Collector 配置文件的 processors 部分配置处理器。你指定的任何设置都会覆盖已有默认值。

下面的示例在同一配置文件中展示了几个默认处理器。合并 opentelemetry-collector-contrib 与 opentelemetry-collector 中的处理器列表,就能得到完整列表。

processors:
  # Data sources: traces
  attributes:
    actions:
      - key: environment
        value: production
        action: insert
      - key: db.statement
        action: delete
      - key: email
        action: hash

  # Data sources: traces, metrics, logs
  filter:
    error_mode: ignore
    traces:
      span:
        - 'attributes["container.name"] == "app_container_1"'
        - 'resource.attributes["host.name"] == "localhost"'
        - 'name == "app_3"'
      spanevent:
        - 'attributes["grpc"] == true'
        - 'IsMatch(name, ".*grpc.*")'
    metrics:
      metric:
        - 'name == "my.metric" and resource.attributes["my_label"] == "abc123"'
        - 'type == METRIC_DATA_TYPE_HISTOGRAM'
      datapoint:
        - 'metric.type == METRIC_DATA_TYPE_SUMMARY'
        - 'resource.attributes["service.name"] == "my_service_name"'
    logs:
      log_record:
        - 'IsMatch(body, ".*password.*")'
        - 'severity_number < SEVERITY_NUMBER_WARN'

  # Data sources: traces, metrics, logs
  memory_limiter:
    check_interval: 5s
    limit_mib: 4000
    spike_limit_mib: 500

  # Data sources: traces
  resource:
    attributes:
      - key: cloud.zone
        value: zone-1
        action: upsert
      - key: k8s.cluster.name
        from_attribute: k8s-cluster
        action: insert
      - key: redundant-attribute
        action: delete

  # Data sources: traces
  probabilistic_sampler:
    hash_seed: 22
    sampling_percentage: 15

  # Data sources: traces
  span:
    name:
      to_attributes:
        rules:
          - ^\/api\/v1\/document\/(?P<documentId>.*)\/update$
      from_attributes: [db.svc, operation]
      separator: '::'

导出器 导出器图标

导出器将数据发送到一个或多个后端或目标。它们可以采用拉取方式,也可以采用推送方式,并可能支持一种或多种 数据源。

exporters 部分中的每个键定义一个导出器实例。键使用 type/name 格式,其中 type 指定导出器类型,例如 otlp、kafka、prometheus;可选的 name 可以附加在后面,为同一类型的多个实例提供唯一名称。

大多数导出器至少需要配置目标地址,以及身份验证令牌或 TLS 证书等安全设置。你指定的任何设置都会覆盖已有默认值。

Collector 需要至少一个导出器。下面的示例在同一配置文件中展示了多种导出器:

exporters:
  # Data sources: traces, metrics, logs
  file:
    path: ./filename.json

  # Data sources: traces
  otlp_grpc/jaeger:
    endpoint: jaeger-server:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # Data sources: traces, metrics, logs
  kafka:
    protocol_version: 2.0.0
  # Data sources: traces, metrics, logs
  # NOTE: Prior to v0.86.0 use `logging` instead of `debug`
  debug:
    verbosity: detailed

  # Data sources: traces, metrics
  opencensus:
    endpoint: otelcol2:55678

  # Data sources: traces, metrics, logs
  otlp_grpc:
    endpoint: otelcol2:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # Data sources: traces, metrics
  otlp_http:
    endpoint: https://otlp.example.com:4318

  # Data sources: metrics
  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: default

  # Data sources: metrics
  prometheus_remote_write:
    endpoint: http://prometheus.example.com:9411/api/prom/push
    # When using the official Prometheus (running via Docker)
    # endpoint: 'http://prometheus:9090/api/v1/write', add:
    # tls:
    #   insecure: true

  # Data sources: traces
  zipkin:
    endpoint: http://zipkin.example.com:9411/api/v2/spans

注意,有些导出器需要 X.509 证书才能建立安全连接,详见 配置证书。

连接器 连接器图标

连接器连接两条流水线,同时充当导出器和接收器。连接器在一条流水线末端以导出器身份消费数据,在另一条流水线开端以接收器身份发出数据。消费和发出的数据可以是同一种类型,也可以是不同类型。连接器可用于汇总消费的数据、复制数据或进行路由。

可以通过 Collector 配置文件的 connectors 部分配置一个或多个连接器。默认不配置连接器。每一种连接器都为一种或多种数据类型配对设计,只能用于连接相应的流水线。

下面的示例展示 count 连接器及其在 pipelines 部分的配置方式。注意,它充当 traces 的导出器和 metrics 的接收器,将两条流水线连接起来:

receivers:
  foo:

exporters:
  bar:

connectors:
  count:
    spanevents:
      my.prod.event.count:
        description: The number of span events from my prod environment.
        conditions:
          - 'attributes["env"] == "prod"'
          - 'name == "prodevent"'

service:
  pipelines:
    traces:
      receivers: [foo]
      exporters: [count]
    metrics:
      receivers: [count]
      exporters: [bar]

扩展 扩展图标

扩展是可选组件,用于扩展 Collector 的能力,完成不直接涉及遥测数据处理的任务。例如,可以添加用于 Collector 健康监控、服务发现或数据转发的扩展。

可以通过 Collector 配置文件的 extensions 部分配置扩展。大多数扩展提供默认设置,因此只指定扩展名称即可配置。你指定的任何设置都会覆盖已有默认值。

默认不配置扩展。下面的示例在同一文件中配置了多个扩展:

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

Service 部分

service 部分依据 receivers、processors、exporters 和 extensions 部分中的配置,确定 Collector 中启用哪些组件。组件即使已经配置,只要没有在 service 部分定义,就不会启用。

service 部分包含三个子部分:

  • Extensions(扩展)
  • Pipelines(流水线)
  • Telemetry(遥测)

扩展

extensions 子部分包含需要启用的扩展列表。例如:

service:
  extensions: [health_check, pprof, zpages]

流水线

pipelines 子部分用于配置流水线,可以是以下类型:

  • traces:收集和处理追踪数据。
  • metrics:收集和处理指标数据。
  • logs:收集和处理日志数据。

一条流水线由一组接收器、处理器和导出器组成。在将接收器、处理器或导出器加入流水线之前,务必在相应部分定义其配置。

可以在多条流水线中使用同一个接收器、处理器或导出器。当多条流水线引用同一个处理器时,每条流水线都会获得该处理器的独立实例。

下面是流水线配置示例。注意,处理器的顺序决定数据处理的顺序:

service:
  pipelines:
    metrics:
      receivers: [opencensus, prometheus]
      exporters: [opencensus, prometheus]
    traces:
      receivers: [opencensus, jaeger]
      processors: [memory_limiter]
      exporters: [opencensus, zipkin]

与组件一样,使用 type[/name] 语法可以为同一类型创建额外流水线。下面的示例扩展了前面的配置:

service:
  pipelines:
    # ...
    traces:
      # ...
    traces/2:
      receivers: [opencensus]
      exporters: [zipkin]

遥测

telemetry 配置部分用于设置 Collector 自身的可观测性。它包含 logs 和 metrics 两个子部分。了解如何配置这些信号,请参阅 激活 Collector 内部遥测。

其他信息

环境变量

Collector 配置支持使用和展开环境变量。例如,要使用 DB_KEY 和 OPERATION 环境变量中存储的值,可以编写以下配置:

processors:
  attributes/example:
    actions:
      - key: ${env:DB_KEY}
        action: ${env:OPERATION}

可以使用 Bash 语法为环境变量提供默认值:${env:DB_KEY:-some-default-var}。

processors:
  attributes/example:
    actions:
      - key: ${env:DB_KEY:-mydefault}
        action: ${env:OPERATION:-}

使用 $$ 表示字面量 $。例如,表示 $DataVisualization 时应写成以下形式:

exporters:
  prometheus:
    endpoint: prometheus:8889
    namespace: $$DataVisualization

代理支持

使用 net/http 包的导出器遵循以下代理环境变量:

  • HTTP_PROXY:HTTP 代理地址。
  • HTTPS_PROXY:HTTPS 代理地址。
  • NO_PROXY:不得使用代理的地址。

如果在 Collector 启动时设置这些环境变量,无论协议为何,导出器都会按照它们的定义通过代理发送流量或绕过代理。

身份验证

大多数开放 HTTP 或 gRPC 端口的接收器可以使用 Collector 的身份验证机制进行保护。同样,大多数使用 HTTP 或 gRPC 客户端的导出器可以为发出的请求添加身份验证。

Collector 的身份验证机制基于扩展机制,因此可将自定义身份验证器插入 Collector 发行版。每个身份验证扩展有两种可能的用法:

  • 为导出器充当客户端身份验证器,向发出的请求添加身份验证数据。
  • 为接收器充当服务器身份验证器,验证传入连接。

已知身份验证器列表请参阅 注册表。如果希望开发自定义身份验证器,请参阅 构建身份验证器扩展。

在 Collector 中为接收器添加服务器身份验证器时,请执行以下步骤:

  1. 在 .extensions 下添加身份验证器扩展及其配置。
  2. 在 .services.extensions 中添加对身份验证器的引用,以便 Collector 加载它。
  3. 在 .receivers.<your-receiver>.<http-or-grpc-config>.auth 下添加对身份验证器的引用。

下面的示例在接收器端使用 OIDC 身份验证器,适合由作为代理的 OpenTelemetry Collector 向远程 Collector 发送数据的场景。

extensions:
  oidc:
    issuer_url: http://localhost:8080/auth/realms/opentelemetry
    audience: collector

receivers:
  otlp/auth:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        auth:
          authenticator: oidc

processors:
exporters:
  # NOTE: Prior to v0.86.0 use `logging` instead of `debug`.
  debug:

service:
  extensions:
    - oidc
  pipelines:
    traces:
      receivers:
        - otlp/auth
      processors: []
      exporters:
        - debug

在代理端,下面的示例使 OTLP 导出器获取 OIDC 令牌,并将其添加到发往远程 Collector 的每个 RPC 中:

extensions:
  oauth2client:
    client_id: agent
    client_secret: some-secret
    token_url: http://localhost:8080/auth/realms/opentelemetry/protocol/openid-connect/token

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

processors:

exporters:
  otlp_grpc/auth:
    endpoint: remote-collector:4317
    auth:
      authenticator: oauth2client

service:
  extensions:
    - oauth2client
  pipelines:
    traces:
      receivers:
        - otlp
      processors: []
      exporters:
        - otlp_grpc/auth

配置证书

在生产环境中,使用 TLS 证书保护通信,或使用 mTLS 进行双向身份验证。下面的步骤展示如何生成示例中的自签名证书。用于生产时,可以采用你现有的证书供应流程获取证书。

安装 cfssl,然后创建以下 csr.json 文件:

{
  "hosts": ["localhost", "127.0.0.1"],
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
    {
      "O": "OpenTelemetry Example"
    }
  ]
}

然后运行以下命令:

cfssl genkey -initca csr.json | cfssljson -bare ca
cfssl gencert -ca ca.pem -ca-key ca-key.pem csr.json | cfssljson -bare cert

这会创建两个证书:

  • ca.pem 中的“OpenTelemetry Example”证书颁发机构(CA),以及 ca-key.pem 中的关联密钥。
  • cert.pem 中的客户端证书,由 OpenTelemetry Example CA 签名,其关联密钥位于 cert-key.pem。

在 Collector 中使用证书

获得证书后,配置 Collector 使用它们。

接收器的 TLS 配置(服务器端)

在接收器上配置 TLS,以加密传入连接。使用 cert_file 和 key_file 指定服务器证书:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /path/to/cert.pem
          key_file: /path/to/cert-key.pem
      http:
        endpoint: 0.0.0.0:4318
        tls:
          cert_file: /path/to/cert.pem
          key_file: /path/to/cert-key.pem

导出器的 TLS 配置(客户端)

在导出器上配置 TLS,以加密发出的连接。使用 ca_file 验证服务器证书:

exporters:
  otlp_grpc:
    endpoint: otelcol2:4317
    tls:
      ca_file: /path/to/ca.pem

如果还需要向服务器提供客户端证书:

exporters:
  otlp_grpc:
    endpoint: otelcol2:4317
    tls:
      ca_file: /path/to/ca.pem
      cert_file: /path/to/cert.pem
      key_file: /path/to/cert-key.pem

mTLS 配置(双向 TLS)

对于 mTLS,接收器和导出器都会验证对方的证书。在接收器上添加 client_ca_file 来验证客户端证书:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /path/to/server-cert.pem
          key_file: /path/to/server-key.pem
          client_ca_file: /path/to/ca.pem

在导出器上,同时提供验证服务器所需的 CA 证书和客户端证书:

exporters:
  otlp_grpc:
    endpoint: remote-collector:4317
    tls:
      ca_file: /path/to/ca.pem
      cert_file: /path/to/client-cert.pem
      key_file: /path/to/client-key.pem

常见 TLS 设置

TLS 配置支持以下设置:

设置 说明
ca_file 用于验证对端证书的 CA 证书路径
cert_file TLS 证书路径
key_file TLS 私钥路径
client_ca_file 用于验证客户端证书的 CA 证书路径
insecure 禁用 TLS 验证(不建议用于生产)
insecure_skip_verify 跳过服务器证书验证(不建议)
min_version 最低 TLS 版本,例如 1.2 或 1.3
max_version 最高 TLS 版本
reload_interval 重新加载证书的时间间隔

覆盖设置

可以使用 --set 选项覆盖 Collector 设置。以这种方式定义的设置会在所有 --config 来源解析并合并之后,再合并到最终配置中。

以下示例展示如何覆盖嵌套部分中的设置:

简单属性

--set 选项始终接受一个键值对,用法为 --set key=value。对应的 YAML 为:

key: value

复杂嵌套键

在键值对名称中使用双冒号 :: 作为键分隔符,可以引用嵌套映射值。例如,--set outer::inner=value 转换为:

outer:
  inner: value

多个值

要设置多个值,请指定多个 --set 标志。因此,--set a=b --set c=d 会转换为:

a: b
c: d

数组值

用 [] 将值括起来,可以表示数组。例如,--set "key=[a, b, c]" 转换为:

key:
  - a
  - b
  - c

如果需要表示更复杂的数据结构,强烈建议使用 YAML。

--set 选项有以下限制:

  1. 不支持设置包含点号 . 的键。
  2. 不支持设置包含等号 = 的键。
  3. 属性值部分中的配置键分隔符为 ::。例如,--set "name={a::b: c}" 等价于 --set name::a::b=c。

嵌入其他配置提供程序

一个配置提供程序可以引用其他配置提供程序,如下所示:

receivers:
  otlp:
    protocols:
      grpc:

exporters: ${file:otlp-exporter.yaml}

service:
  extensions: []
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlp_grpc]

检查发行版中可用的组件

使用 build-info 子命令。下面是示例:

otelcol components

示例输出:

buildinfo:
  command: otelcol
  description: OpenTelemetry Collector
  version: 0.143.0
receivers:
  - otlp
processors:
  - memory_limiter
exporters:
  - otlp_grpc
  - otlp_http
  - debug
extensions:
  - zpages

检查最终配置

在默认模式 --mode=redacted 下使用 print-config,并启用 --feature-gates=otelcol.printInitialConfig:

otelcol print-config --config=file:examples/local/otel-config.yaml

注意,默认只会打印有效配置,并会对敏感信息进行脱敏。要打印可能无效的配置,请使用 --validate=false。

查看敏感字段

使用 print-config,设置 --mode=unredacted 并启用 --feature-gates=otelcol.printInitialConfig:

otelcol print-config --mode=unredacted --config=file:examples/local/otel-config.yaml

以 JSON 格式打印最终配置

使用 print-config,设置 --format=json 并启用 --feature-gates=otelcol.printInitialConfig。注意,JSON 格式被视为不稳定。

otelcol print-config --format=json --config=file:examples/local/otel-config.yaml

来源:OpenTelemetry — Configuration,OpenTelemetry Authors。原页最后修改:2026年9月10日。本中文翻译与文章内排版为改编,代码保留原文。原始文档适用 CC BY 4.0,官方许可。本页示例输出的版本号为0.143.0,不代表当前所有发行版。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容