otel-collector

OpenTelemetry Collector 配置指南

有关配置和部署 OpenTelemetry Collector 以接收、处理和导出遥测数据的专家指导。

规则

规则	描述
receivers	接收器——OTLP、Prometheus、filelog、hostmetrics
exporters	导出器——通过 OTLP/gRPC 导出到 Dash0、debug、身份验证
processors	处理器——内存限制器、资源检测、顺序、发送队列
pipelines	管道——service 部分、按信号类型配置、连接器
deployment	部署——Agent 与网关模式、部署方式选择
dash0-operator	Dash0 Kubernetes Operator——自动化插桩、Collector 管理、导出到 Dash0
collector-helm-chart	Collector Helm chart——预设、模式、镜像选择
opentelemetry-operator	OpenTelemetry Operator——Collector CRD、自动插桩、sidecar
raw-manifests	原始 Kubernetes 清单——DaemonSet、Deployment、RBAC、Docker Compose
sampling	采样——头部采样、尾部采样、负载均衡
red-metrics	RED 指标——基于 span 生成的请求速率、错误率、持续时间直方图
custom-distributions	自定义发行版——使用 OCB 构建精简版 Collector 二进制文件

关键原则

• 处理器顺序很重要。 在每个管道中将 memory_limiter 放在首位。 启用导出器批处理：使用 sending_queue: { batch: {} }，并通过 file_storage 持久化队列，而不要使用 batch 处理器。 顺序错误会导致内存耗尽或数据丢失。
• 每种信号类型使用一个管道。 分别为 traces、metrics 和 logs 定义管道。 在单个管道中混合信号会破坏处理流程并导致运行时错误。
• 每个声明的组件都必须出现在某个管道中。 Collector 会忽略没有被任何管道引用的组件，且不会报错或发出警告，因此未接入管道的组件不会执行任何操作。
• 确保各管道的资源丰富信息保持一致。 在每种信号类型的管道（traces、metrics 和 logs）中都应用丰富资源属性的处理器，例如 resource_detection 和 k8s_attributes，而不只是应用于某个管道。 如果一个管道使用 k8s.namespace.name 或 host.name 丰富遥测数据，而另一个管道没有这样做，元数据不完整就会影响信号间的关联。
• 使用规范的组件名称。 在配置项中使用 otlp_grpc、otlp_http、load_balancing、span_metrics、log_dedup、signal_to_metrics、k8s_attributes 和 resource_detection。 较旧的名称 otlp（仅用于 exporter）、otlphttp、loadbalancing、spanmetrics、logdedup、signaltometrics、k8sattributes 和 resourcedetection 仍可作为已弃用的别名使用，并会在启动时记录弃用警告。
• 运行 Collector v0.153.0 或更高版本。 此技能中的配置需要该版本：load_balancing 和 resource_detection 仅从 v0.153.0 开始提供，sending_queue.batch: {} 仅从 v0.138.0 开始提供。 较旧版本的 Collector 会在启动时拒绝这些配置：新名称会报 unknown type；对于 batch: {}，则会报 'sending_queue' has invalid keys: batch 或 `batch` supports only `items` or `bytes` sizer。 固定镜像版本时，请使用示例所基于的版本 v0.163.1。
• 内存安全不容妥协。 在生产环境中始终配置 memory_limiter。 如果不配置，突发的遥测数据可能导致 Collector 内存溢出并崩溃。

快速开始

最简可运行配置：OTLP 接收器 → 内存限制器 → OTLP/gRPC 导出器，发送到 Dash0。

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

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 400
    spike_limit_mib: 100

exporters:
  otlp_grpc:
    endpoint: ingress.eu-west-1.aws.dash0.com:4317
    headers:
      Authorization: "Bearer ${env:DASH0_TOKEN}"
    sending_queue:
      enabled: true
      storage: file_storage
      batch: {}

extensions:
  file_storage:
    directory: /var/lib/otelcol/queue
    create_directory: true

service:
  extensions: [file_storage]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]

Collector 用户必须能够写入 file_storage 目录；在容器中，请在 /var/lib/otelcol 挂载持久卷。

完整的身份验证和队列配置请参阅导出器，添加资源检测请参阅处理器。

配置工作流

1. 编写配置 — 定义接收器、处理器和导出器；在 service.pipelines 中将它们连接起来。
2. 本地验证 — 运行 otelcol validate --config=config.yaml，在部署前发现结构错误。
3. 部署 — 从部署规则中选择一种部署方法（Helm、Operator、原始清单或 Docker Compose）。
4. 验证 — 暂时将 debug 导出器添加到管道，并检查标准输出以确认遥测数据正在流动；然后在投入生产前将其移除。

快速参考

您需要什么？	规则
接收来自应用程序的 OTLP 遥测数据	接收器
抓取 Prometheus 端点	接收器
收集日志文件或主机指标	接收器
将遥测数据发送到 Dash0	导出器
配置重试、队列或压缩	导出器
设置处理器顺序	处理器
添加 Kubernetes 或云元数据	处理器
连接接收器 → 处理器 → 导出器	管道
完整的可运行配置	管道
使用 debug 导出器验证管道	collector-helm-chart、opentelemetry-operator、raw-manifests 或 dash0-operator
以 DaemonSet 或 Deployment 方式部署	raw-manifests
使用 Helm 部署	collector-helm-chart
使用 OTel Operator 部署	opentelemetry-operator
使用 Dash0 Operator 部署	dash0-operator
在 Kubernetes 中自动为应用程序插桩	opentelemetry-operator 或 dash0-operator
使用 Docker Compose 进行本地开发	raw-manifests
减少追踪数据量	采样
保留错误和慢速追踪，丢弃其余数据	采样
在管道中隐藏敏感数据	处理器
从追踪生成 RED 指标	red-metrics
构建自定义 Collector 二进制文件	custom-distributions

官方文档

• OpenTelemetry Collector 文档
• Collector 配置
• Collector contrib 组件
• Dash0 集成中心