配置选项

OpenTelemetry Collector 架构由五种主要组件类型组成，它们协同工作，以处理整个生命周期中的 telemetry 数据：

Receivers：将 telemetry 数据摄取到 Collector 中的组件
Processors：在数据通过 pipeline 流动时对其进行转换、过滤或增强的组件
Exporters：将处理后的数据发送到后端系统或目标的组件
Connectors：通过同时充当 exporter 和 receiver 来连接 pipeline 段的组件
Extensions：提供辅助功能、但不直接处理 telemetry 数据的可选组件

组件配置

你可以在自定义资源 YAML 文件中为每种组件类型定义多个实例。不过，必须通过 spec.config.service 部分中的 pipeline 定义显式启用组件，组件才会生效。

TIP

最佳实践是仅启用实际需要的组件。这样可以减少资源消耗，并简化故障排查。

配置示例

以下示例演示了一个包含 OTLP receiver 和多个 exporter 的基本 OpenTelemetry Collector 配置：

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: cluster-collector
  namespace: tracing-system
spec:
  mode: deployment
  replicas: 1
  observability:
    metrics:
      enableMetrics: true
  config:
    receivers:
      otlp:
        protocols:
          grpc: {}
          http: {}
    processors: {}
    exporters:
      otlp_grpc:
        endpoint: otel-collector-headless.tracing-system.svc:4317
        tls:
          ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt"
      prometheus:
        endpoint: 0.0.0.0:8889
        resource_to_telemetry_conversion:
          enabled: true # by default resource attributes are dropped
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: []
          exporters: [otlp_grpc]
        metrics:
          receivers: [otlp]
          processors: []
          exporters: [prometheus]

OTLP exporter 的名称是 otlp_grpc，而上面的 OTLP receiver 仍保留名称 otlp。请参见组件类型名称。
在配置中定义但未在 service.pipelines 部分引用的组件将保持非活动状态。组件必须至少添加到一个 pipeline 中才能运行。

组件类型名称

上游已将大多数组件类型标识符重命名为 snake_case，并将两个 OTLP exporter 重命名，以便在名称中明确传输协议：

组件	已弃用的类型名称	当前类型名称
OTLP gRPC exporter	`otlp`	`otlp_grpc`
OTLP HTTP exporter	`otlphttp`	`otlp_http`

已弃用的名称仍然可用，因此现有配置可以继续运行，但 Collector 会针对每个受影响的组件实例记录一条警告，并且上游计划在未来版本中移除这些别名：

warn  builders/builders.go:40  "otlp" alias is deprecated; use "otlp_grpc" instead
  {"otelcol.component.id": "otlp/traces", "otelcol.component.kind": "exporter", "otelcol.signal": "traces"}

完整的重命名组件列表请参见 v2.1.0 Release Notes。

配置参数

下表描述了 Operator 用于定义 OpenTelemetry Collector 的主要配置参数：

参数	描述	值	默认值
`receivers`	定义数据进入 Collector 的方式。要使配置有效，pipeline 中必须至少启用一个 receiver。	otlp, jaeger, prometheus, zipkin, kafka	无
`processors`	定义接收和导出之间应用的数据转换操作。Processor 是可选的。	batch, memory_limiter, resource_detection, attributes, span, k8s_attributes, filter	无
`exporters`	定义处理后数据的目标。要使配置有效，pipeline 中必须至少启用一个 exporter。	otlp_grpc, otlp_http, debug, prometheus, kafka	无
`connectors`	定义作为 exporter 消费数据、作为 receiver 发出数据，从而连接 pipeline 对的组件。	span_metrics, count, routing, forward	无
`extensions`	定义用于辅助任务、且不涉及 telemetry 数据处理的可选组件。	bearertokenauth, oauth2client, pprof, health_check, zpages	无
`service.pipelines`	通过将组件添加到 pipeline 中来启用它们。组件必须列在此处才会生效。	N/A	无

Values 列仅列出了代表性组件。有关受支持组件及其当前类型名称的完整列表，请参见 Receivers、Processors、Exporters、Connectors 和 Extensions。

Pipeline 配置

Pipeline 定义在 service.pipelines 下，用于指定 telemetry 数据在 Collector 中的流向。每种 pipeline 类型（traces、metrics、logs）都可以拥有自己的一组 receiver、processor 和 exporter。

示例 pipeline 配置：

service:
  pipelines:
    traces:
      receivers: [otlp, jaeger]
      processors: [batch, memory_limiter]
      exporters: [otlp_grpc, debug]
    metrics:
      receivers: [otlp, prometheus]
      processors: [batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc]

每个 pipeline 会独立处理其 telemetry 类型，因此你可以根据可观测性需求，为 traces、metrics 和 logs 配置不同的处理逻辑。

Collector 资源选项

上面的字段位于 spec.config 下，用于配置 Collector 进程本身。OpenTelemetryCollector 自定义资源还公开了用于控制 Operator 如何部署 Collector 工作负载的字段。

字段	描述
`spec.command`	覆盖 Collector 容器的 entrypoint，其语义与 `Pod.spec.containers[].command` 相同。接受字符串数组。若省略，则使用镜像的 `ENTRYPOINT`。
`spec.hostAliases`	向 pod 的 `hosts` 文件中添加条目，与 `Pod.spec.hostAliases` 行为一致。当 Collector 必须解析集群 DNS 不提供的后端主机名时，这很有用。
`spec.podManagementPolicy`	设置底层 StatefulSet 的 pod 创建和终止顺序。仅在 `spec.mode` 为 `statefulset` 时适用。默认值为 `Parallel`。
`spec.sessionAffinity`	设置 Operator 为 Collector 创建的每个 Service 的 session affinity，行为与 `Service.spec.sessionAffinity` 一致。可接受 `ClientIP`，它会将来自同一客户端 IP 的所有请求路由到同一个 Collector replica，或 `None`。默认值为 `None`。在 `sidecar` 模式下无效，因为该模式不会创建 Service。
`spec.sessionAffinityConfig.clientIP.timeoutSeconds`	设置 `ClientIP` affinity 条目的保留时长，行为与 `Service.spec.sessionAffinityConfig` 一致。默认值为 `10800`（3 小时）。仅在 `spec.sessionAffinity` 为 `ClientIP` 时读取。
`spec.observability.metrics.enableMetrics`	指示 Operator 为 Collector 创建 `ServiceMonitor` 或 `PodMonitor` 资源。请参见配置 Collector 指标。
`spec.observability.metrics.disablePrometheusAnnotations`	阻止 Operator 将默认的 `prometheus.io/scrape`、`prometheus.io/port` 和 `prometheus.io/path` 注解写入 pod 模板。对于现有 Collector，将其设置为 `true` 还会移除 Operator 之前添加的注解，同时保留你自行设置的注解不变。

示例：

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel
spec:
  mode: statefulset
  replicas: 2
  podManagementPolicy: Parallel
  hostAliases:
    - ip: "10.0.0.10"
      hostnames:
        - "backend.internal"
  sessionAffinity: ClientIP
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 10800
  config:
    receivers:
      otlp:
        protocols:
          grpc: {}
    exporters:
      debug: {}
    service:
      pipelines:
        traces:
          receivers: [otlp]
          exporters: [debug]

仅在 statefulset 模式下有意义。对于 deployment、daemonset 和 sidecar 模式，请保持未设置。
每个条目会将一个 IP 地址映射到 Collector pod 内的一个或多个主机名。
将每个客户端 IP 固定到一个 Collector replica。sessionAffinityConfig 是可选的；如果省略，则保持默认的 3 小时超时。

Ingress 和 Gateway API

Operator 可以通过 Ingress 资源或 Gateway API HTTPRoute 资源公开 Collector 的 receiver 端口。两者都仅在 deployment、daemonset 和 statefulset 模式下可用。

spec.ingress 会创建一个 Ingress 资源。在此字段下配置主机名、注解和 TLS 设置。
spec.httpRoute 会创建一个 Gateway API HTTPRoute 资源。当你的集群通过 Gateway API 实现而不是 Ingress controller 来路由南北向流量时，请选择此项。

以下示例将 Collector 连接到一个现有的 Gateway：

spec:
  httpRoute:
    enabled: true
    gateway: my-gateway
    gatewayNamespace: gateway-system
    hostnames:
      - otel.example.com

必填。启用 HTTPRoute 配置。
必填。要附加该 route 的 Gateway 资源名称。
Gateway 资源所在的 namespace。默认值为 Collector 自身的 namespace。
该 route 匹配的主机名。为空时，route 将匹配任意主机名。

Collector 状态

OpenTelemetryCollector 资源通过 status.observedGeneration 和 status.conditions 报告 reconciliation 状态。等待 Collector 收敛的自动化逻辑应在读取 conditions 之前，将 status.observedGeneration 与 metadata.generation 进行比较，以免基于资源早期版本生成的状态进行操作。

kubectl get opentelemetrycollector <name> -n <namespace> \
  -o jsonpath='{.metadata.generation} {.status.observedGeneration}{"\n"}'

#配置选项

#目录

#组件配置

#配置示例

#组件类型名称

#配置参数

#Pipeline 配置

#Collector 资源选项

#Ingress 和 Gateway API

#Collector 状态