配置

了解如何配置 Collector 以满足您的需求

您可以配置 OpenTelemetry Collector 以满足您的可观测性需求。在了解 Collector 配置的工作原理之前，请先熟悉以下内容

数据收集概念，以了解适用于 OpenTelemetry Collector 的存储库。
面向最终用户的安全指南
面向组件开发者的安全指南

位置

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

您可以使用 --config 选项提供一个或多个配置。例如

otelcol --config=customconfig.yaml

您还可以使用不同路径的多个文件来提供多个配置。每个文件可以是完整的或部分配置，并且文件可以相互引用组件。如果合并后的文件不构成完整配置，用户将收到错误，因为必需的组件默认不会添加。按如下方式在命令行中传递多个文件路径

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"

提示

在引用 YAML 路径中的嵌套键时，请确保使用双冒号 (::) 以避免与包含点的命名空间混淆。例如：receivers::docker_stats::metrics::container.cpu.utilization::enabled: false。

要验证配置文件，请使用 validate 命令。例如

otelcol validate --config=customconfig.yaml

配置结构

任何 Collector 配置文件都包含四个类别的管道组件，用于访问遥测数据

接收器
处理器
导出器
连接器

配置完每个管道组件后，您必须在配置文件中的 service 部分使用管道来启用它。

除了管道组件，您还可以配置 extensions，它们提供可以添加到 Collector 的功能，例如诊断工具。扩展不需要直接访问遥测数据，并且通过 service 部分启用。

以下是 Collector 配置示例，其中包含一个接收器、一个处理器、一个导出器和三个扩展。

重要提示

虽然在所有客户端都本地的情况下，通常最好将端点绑定到 localhost，但我们的示例配置出于方便使用“未指定”地址 0.0.0.0。Collector 当前默认为 0.0.0.0，但在不久的将来，默认值将更改为 localhost。有关作为端点配置值的这两个选择的详细信息，请参阅防止拒绝服务攻击的安全措施。

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

exporters:
  otlp:
    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]
    metrics:
      receivers: [otlp]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      exporters: [otlp]

请注意，接收器、处理器、导出器和管道通过组件标识符定义，格式为 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:
    endpoint: otelcol:4317
    sending_queue:
      batch:
  otlp/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]
    traces/2:
      receivers: [otlp/2]
      exporters: [otlp/2]
    metrics:
      receivers: [otlp]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      exporters: [otlp]

配置还可以包含其他文件，导致 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]

exporters.yaml 文件内容如下

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

内存中的最终结果将是

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

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

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

接收器

接收器从一个或多个源收集遥测数据。它们可以是拉取式或推送式，并且可能支持一个或多个数据源。

接收器在 receivers 部分进行配置。许多接收器都带有默认设置，因此只需指定接收器名称即可进行配置。如果您需要配置接收器或想更改默认配置，可以在此部分进行。您指定的任何设置都将覆盖存在的默认值。

配置接收器并不会启用它。通过在 service 部分中将接收器添加到相应的管道来启用接收器。

Collector 需要一个或多个接收器。以下示例显示了同一配置文件中的各种接收器

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

  # Data sources: metrics
  hostmetrics:
    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:

有关详细的接收器配置，请参阅接收器 README。

处理器

处理器在将数据发送到导出器之前，会接收由接收器收集的数据并对其进行修改或转换。数据处理根据每个处理器定义的规则或设置进行，这些设置可能包括过滤、丢弃、重命名或重新计算遥测数据等操作。管道中处理器的顺序决定了 Collector 应用于信号的处理操作的顺序。

处理器是可选的，尽管建议使用某些处理器。

您可以使用 Collector 配置文件中的 processors 部分来配置处理器。您指定的任何设置都将覆盖存在的默认值。

配置处理器并不会启用它。通过在 service 部分中将处理器添加到相应的管道来启用处理器。

以下示例显示了同一配置文件中的多个默认处理器。您可以通过组合 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: metrics, 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: '::'

有关详细的处理器配置，请参阅处理器 README。

导出器

导出器将数据发送到一个或多个后端或目的地。导出器可以是拉取式或推送式，并且可能支持一个或多个数据源。

exporters 部分中的每个键都定义了一个导出器实例。键遵循 type/name 格式，其中 type 指定导出器类型（例如 otlp、kafka、prometheus），而 name（可选）可以追加以提供同一类型多个实例的唯一名称。

大多数导出器都需要配置以指定至少目的地，以及安全设置，如身份验证令牌或 TLS 证书。您指定的任何设置都将覆盖存在的默认值。

配置导出器并不会启用它。通过在 service 部分中将导出器添加到相应的管道来启用导出器。

Collector 需要一个或多个导出器。以下示例显示了同一配置文件中的各种导出器

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

  # Data sources: traces
  otlp/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:
    endpoint: otelcol2:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

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

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

  # Data sources: metrics
  prometheusremotewrite:
    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 证书才能建立安全连接，如设置证书中所述。

有关导出器配置的更多信息，请参阅 exporter README.md。

连接器

连接器连接两个管道，充当导出器和接收器。连接器在一个管道末端作为导出器消耗数据，并在另一个管道开头作为接收器发出数据。消耗和发出的数据可以是相同类型或不同数据类型的。您可以使用连接器来汇总、复制或路由消耗的数据。

您可以使用 Collector 配置文件中的 connectors 部分来配置一个或多个连接器。默认情况下，不配置任何连接器。每种类型的连接器都设计为与一个或多个数据类型对配合使用，并且只能用于相应地连接管道。

配置连接器并不会启用它。连接器通过 service 部分中的管道来启用。

以下示例显示了 count 连接器以及它在 pipelines 部分中的配置。请注意，连接器充当跟踪数据的导出器和指标数据的接收器，连接了两个管道

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]

有关详细的连接器配置，请参阅连接器 README。

扩展

扩展是可选组件，它们扩展了 Collector 的功能，以完成与直接处理遥测数据无关的任务。例如，您可以添加用于 Collector 健康监控、服务发现或数据转发等功能的扩展。

您可以通过 Collector 配置文件中的 extensions 部分来配置扩展。大多数扩展都带有默认设置，因此您只需指定扩展名称即可进行配置。您指定的任何设置都将覆盖存在的默认值。

配置扩展并不会启用它。扩展在 service 部分中启用。

默认情况下，不配置任何扩展。以下示例显示了同一文件中配置的多个扩展

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

有关详细的扩展配置，请参阅扩展 README。

服务部分

service 部分用于根据 receivers、processors、exporters 和 extensions 部分中的配置来确定 Collector 中启用了哪些组件。如果一个组件已配置但未在 service 部分中定义，则它不会被启用。

service 部分包含三个子部分

扩展
管道
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 中的接收器，请执行以下步骤

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

以下示例在接收器端使用 OIDC 身份验证器，使其适用于接收来自充当代理的 OpenTelemetry Collector 的远程 Collector

extensions:
  oidc:
    issuer_url: https://: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: https://:8080/auth/realms/opentelemetry/protocol/openid-connect/token

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

processors:

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

service:
  extensions:
    - oauth2client
  pipelines:
    traces:
      receivers:
        - otlp
      processors: []
      exporters:
        - otlp/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

这将创建两个证书

一个“OpenTelemetry 示例”证书颁发机构 (CA) 在 ca.pem 中，其关联的密钥在 ca-key.pem 中
一个客户端证书在 cert.pem 中，由 OpenTelemetry 示例 CA 签名，其关联的密钥在 cert-key.pem 中。

覆盖设置

您可以使用 --set 选项覆盖 Collector 设置。通过此方法定义的设置将在所有 --config 源解析和合并后合并到最终配置中。

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

otelcol --set "exporters::debug::verbosity=detailed"
otelcol --set "receivers::otlp::protocols::grpc={endpoint:localhost:4317, compression: gzip}"

重要提示

--set 选项不支持设置包含点或等号的键。

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改日期：2025 年 12 月 13 日： docs: Create new Extend the Collector section and rename child pages (#8599) (6a7f1745)