配置

我们假设您已熟悉以下页面：

基本概念

Collector 由四个访问遥测数据的组件组成：

配置这些组件后，必须通过 service 部分中的管道来启用它们。

其次，有一些 扩展，提供可以添加到 Collector 的功能，但不需要直接访问遥测数据，也不是管道的一部分。它们在 service 部分中也会启用。

以下是一个配置示例：

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlp:
    endpoint: otelcol:4317

extensions:
  health_check:
  pprof:
  zpages:

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

请注意，receiver、processor、exporter 和/或 pipeline 是以 type[/name] 格式（例如 otlp 或 otlp/2）定义的组件标识符。同一类型的组件可以定义多次，只要标识符是唯一的。例如：

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

processors:
  batch:
  batch/test:

exporters:
  otlp:
    endpoint: otelcol:4317
  otlp/2:
    endpoint: otelcol2:4317

extensions:
  health_check:
  pprof:
  zpages:

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

配置也可以包括其他文件，并导致 Collector 将两个文件合并为 YAML 配置的单个内存表示形式：

receivers:
  otlp:
    protocols:
      grpc:

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:

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

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

接收器

接收器是数据进入 Collector 的方式，可以是基于推送或拉取的方式。接收器可以支持一个或多个数据源。

receivers: 部分是配置接收器的地方。许多接收器都带有默认设置，因此只需指定接收器的名称就足以对其进行配置（例如 zipkin:）。如果需要配置或者用户想要更改默认配置，则必须在此部分中定义该配置。对于提供默认配置的接收器指定的配置参数将被覆盖。

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

必须配置一个或多个接收器。默认情况下，没有配置任何接收器。以下是接收器的基本示例。

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

receivers:
  # 数据源：日志
  fluentforward:
    endpoint: 0.0.0.0:8006

  # 数据源：指标
  hostmetrics:
    scrapers:
      cpu:
      disk:
      filesystem:
      load:
      memory:
      network:
      process:
      processes:
      paging:

  # 数据源：链路追踪
  jaeger:
    protocols:
      grpc:
      thrift_binary:
      thrift_compact:
      thrift_http:

  # 数据源：链路追踪、指标、日志
  kafka:
    protocol_version: 2.0.0

  # 数据源：链路追踪、指标
  opencensus:

  # 数据源：链路追踪、指标、日志
  otlp:
    protocols:
      grpc:
      http:

  # 数据源：指标
  prometheus:
    config:
      scrape_configs:
        - job_name: otel-collector
          scrape_interval: 5s
          static_configs:
            - targets: [localhost:8888]

  # 数据源：链路追踪
  zipkin:

处理器

处理器是在数据接收和导出之间运行的组件。处理器是可选的，但是某些处理器是推荐的。

processors: 部分是配置处理器的地方。处理器可能带有默认设置，但是许多处理器需要配置。任何处理器的配置都必须在此部分中完成。对于处理器提供默认配置的配置参数将被覆盖。

配置处理器并不会启用它。处理器通过 service 部分中的管道启用。

以下是默认处理器的基本示例。你可以合并此处和此处找到的列表。

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

processors:
  # 数据源：链路追踪
  attributes:
    actions:
      - key: environment
        value: production
        action: insert
      - key: db.statement
        action: delete
      - key: email
        action: hash

  # 数据源：链路追踪、指标、日志
  batch:

  # 数据源：指标
  filter:
    metrics:
      include:
        match_type: regexp
        metric_names:
          - prefix/.*
          - prefix_.*

  # 数据源：链路追踪、指标、日志
  memory_limiter:
    check_interval: 5s
    limit_mib: 4000
    spike_limit_mib: 500

  # 数据源：链路追踪
  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

  # 数据源：链路追踪
  probabilistic_sampler:
    hash_seed: 22
    sampling_percentage: 15

  # 数据源：链路追踪
  span:
    name:
      to_attributes:
        rules:
          - ^\/api\/v1\/document\/(?P<documentId>.*)\/update$
      from_attributes: [db.svc, operation]
      separator: '::'

导出器

导出器是将数据发送到一个或多个后端/目标的方式，可以是基于推送或拉取的方式。导出器可以支持一个或多个数据源。

exporters: 部分是配置导出器的地方。导出器可能带有默认设置，但是许多导出器需要配置，以至少指定目标和安全设置。任何导出器的配置都必须在此部分中完成。对于提供默认配置的配置参数将被覆盖。

配置导出器并不会启用它。导出器通过 service 部分中的管道启用。

必须配置一个或多个导出器。默认情况下，没有配置任何导出器。以下是导出器的基本示例。某些导出器配置要求创建 x.509 证书才能确保安全性，如设置证书中所述。

有关详细的导出器配置，请参见 导出器 README.md。

exporters:
  # 数据源：链路追踪、指标、日志
  file:
    path: ./filename.json

  # 数据源：链路追踪
  otlp/jaeger:
    endpoint: jaeger-all-in-one:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # 数据源：链路追踪、指标、日志
  kafka:
    protocol_version: 2.0.0

  # 数据源：链路追踪、指标、日志
  # 注意：在 v0.86.0 之前，请使用 `logging` 而不是 `debug`
  debug:
    verbosity: detailed

  # 数据源：链路追踪、指标
  opencensus:
    endpoint: otelcol2:55678

  # 数据源：链路追踪、指标、日志
  otlp:
    endpoint: otelcol2:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # 数据源：链路追踪、指标
  otlphttp:
    endpoint: https://example.com:4318

  # 数据源：指标
  prometheus:
    endpoint: prometheus:8889
    namespace: default

  # 数据源：指标
  prometheusremotewrite:
    endpoint: http://some.url:9411/api/prom/push
    # For official Prometheus (e.g. running via Docker)
    # endpoint: 'http://prometheus:9090/api/v1/write'
    # tls:
    #   insecure: true

  # 数据源：链路追踪
  zipkin:
    endpoint: http://localhost:9411/api/v2/spans

连接器

连接器是一种既是导出器又是接收器的组件。顾名思义，连接器将连接两个管道：它作为一个导出器接收一个管道的数据，作为一个接收器在另一个管道的开始处发送数据。它可以消费和发送相同数据类型的数据，也可以是不同的数据类型。连接器可以生成并发送汇总的数据，也可以简单地复制或路由数据。

connectors: 部分是配置连接器的地方。

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

可以配置一个或多个连接器。默认情况下，没有配置任何连接器。以下是连接器的基本示例。

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

connectors:
  forward:

  count:
    spanevents:
      my.prod.event.count:
        description: my prod 环境的 span 事件数量。
        conditions:
          - 'attributes["env"] == "prod"'
          - 'name == "prodevent"'

  spanmetrics:
    histogram:
      explicit:
        buckets: [100us, 1ms, 2ms, 6ms, 10ms, 100ms, 250ms]
    dimensions:
      - name: http.method
        default: GET
      - name: http.status_code
    dimensions_cache_size: 1000
    aggregation_temporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE'

  servicegraph:
    latency_histogram_buckets: [1, 2, 3, 4, 5]
    dimensions:
      - dimension-1
      - dimension-2
    store:
      ttl: 1s
      max_items: 10

扩展

扩展主要用于不涉及处理遥测数据的任务。扩展包括健康监控、服务发现和数据转发等功能。扩展是可选的。

extensions: 部分是配置扩展的地方。许多扩展都带有默认设置，因此只需指定扩展的名称就足以配置它（例如 health_check:）。如果需要配置或者用户想要更改默认配置，则必须在此部分中定义该配置。对于提供默认配置的配置参数将被覆盖。

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

默认情况下，没有配置任何扩展。以下是扩展的基本示例。

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

extensions:
  health_check:
  pprof:
  zpages:
  memory_ballast:
    size_mib: 512

Service

服务部分用于根据在接收器，处理器，导出器和扩展部分中找到的配置来配置在 Collector 中启用的组件。如果配置了组件但未在服务部分中定义，则不会启用该组件。服务部分由以下三个子部分组成：

  • 扩展部分
  • 管道部分
  • 遥测部分

扩展部分

扩展由要启用的所有扩展的列表组成。例如：

service:
  extensions: [health_check, pprof, zpages]

管道部分

管道可以是以下类型之一：

  • traces：收集并处理追踪数据。
  • metrics：收集并处理度量数据。
  • logs：收集并处理日志数据。

管道由一组接收器、处理器和导出器组成。必须在管道之外的配置中定义每个接收器/处理器/导出器，以便将其包含在管道中。

注意： 每个接收器/处理器/导出器可以在多个管道中使用。对于在多个管道中引用的处理器，每个管道将获得该处理器的单独实例。这与在多个管道中引用的接收器/导出器不同，在这种情况下，一个接收器/导出器的实例仅用于所有管道。还要注意，处理器的顺序决定了数据处理的顺序。

以下是管道配置的示例：

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

遥测部分

遥测部分用于配置 Collector 自身生成的遥测。它有两个子部分：logs 和 metrics。

logs 子部分允许配置 Collector 生成的日志。默认情况下，Collector 的日志将写入 stderr，日志级别为 INFO。您还可以使用 initial_fields 部分向所有日志添加静态的键值对。 在此处查看完整的 logs 选项列表。

metrics 子部分允许配置 Collector 生成的度量。默认情况下，Collector 将生成关于自身的基本度量，并在 localhost:8888/metrics 上公开它们供抓取。 在此处查看完整的 metrics 选项列表。

以下是遥测配置的示例：

service:
  telemetry:
    logs:
      level: debug
      initial_fields:
        service: my-instance
    metrics:
      level: detailed
      address: 0.0.0.0:8888

其他信息

配置环境变量

Collector 配置支持使用环境变量的使用和展开。例如，要使用 DB_KEY 和 OPERATION 环境变量上存储的值，可以编写以下内容：

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

使用 $$ 表示字面量 $。例如，表示 $DataVisualization 将如下所示：

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

代理支持

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

  • HTTP_PROXY
  • HTTPS_PROXY
  • NO_PROXY

如果在 Collector 启动时设置了这些环境变量，则无论协议如何，导出器将遵循这些环境变量定义的流量代理或不代理流量。

身份验证

大多数提供 HTTP 或 gRPC 端口的接收器都可以使用 Collector 的身份验证机制进行保护，而使用 HTTP 或 gRPC 客户端的大多数导出器也可以在传出请求中添加身份验证数据。

Collector 中的身份验证机制使用了扩展机制，允许将自定义的身份验证器插入到 Collector 配置中。如果您有兴趣开发自定义的身份验证器，请查看“构建自定义身份验证器”文档。

每个身份验证扩展都有两种可能的用法：作为导出器的客户端身份验证器，将 auth 数据添加到发出的请求中，以及作为接收器的服务器验证器，对传入的连接进行身份验证。请参阅身份验证扩展以获取其功能列表，但通常，身份验证扩展只会实现这些特性之一。可以在公共注册列表中获得已知身份验证器的列表。

要在配置的接收器中添加服务器身份验证器，请确保：

  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:
        auth:
          authenticator: oidc

processors:

exporters:
  # 注意：在 v0.86.0 之前，请使用 `logging` 而不是 `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: localhost: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

这将创建两个证书：

首先，ca.pem 是一个名为 “OpenTelemetry Example” 的证书颁发机构（CA），对应的密钥在 ca-key.pem；然后，cert.pem 是客户端证书（由 OpenTelemetry Example CA 签名），对应的密钥在 cert-key.pem。

最后修改 December 10, 2023: translate (a4350d6e)