📚 课程目录第3章 OpenTelemetry Collector部署

3. OpenTelemetry Collector 部署：Collector 模式、配置文件结构与管道

OpenTelemetry Collector 是 OTel 生态的核心数据平面组件，负责接收、处理、导出遥测数据。在生产环境中，Collector 的部署模式、配置结构与管道编排直接决定了数据采集的可靠性、资源开销与故障自愈能力。本章将系统讲解 Collector 的两种主流部署模式（Agent 与 Gateway）、配置文件的分层结构，以及 Receiver → Processor → Exporter 管道的完整工作机制。

3.1 Collector 部署模式：Agent vs. Gateway

Collector 支持两种部署模式，实际生产环境通常组合使用：Agent 模式部署在每台宿主机或 Pod 侧，负责本地数据采集与轻量预处理；Gateway 模式作为独立集群，负责跨服务的数据聚合、过滤、路由与导出。

对比维度	Agent 模式	Gateway 模式
部署位置	每台宿主机 / 每个 Kubernetes Node / 每个 Pod Sidecar	独立部署的 Collector 集群（通常 2+ 副本）
数据流向	应用 → Agent → 后端 / Gateway	Agent / 应用 → Gateway → 后端
主要职责	本地采集、轻量过滤、属性补充、负载均衡	数据聚合、多租户隔离、重试/背压、全局策略
资源开销	低（通常 50-200MB 内存）	中高（取决于聚合规模）
故障影响面	仅影响单节点	影响所有下游数据流（需高可用）
典型场景	边缘采集、Kubernetes DaemonSet、Sidecar	数据中心级聚合、多集群统一出口

生产建议：推荐采用 Agent + Gateway 两层架构。Agent 负责第一跳采集与本地缓存，Gateway 负责全局策略与后端解耦。当 Agent 与 Gateway 之间网络中断时，Agent 的持久队列（persistent_storage）可防止数据丢失，这是故障自愈的基础保障。

3.2 Collector 配置文件结构

Collector 使用 YAML 配置文件，核心结构包含四个顶级区块：receivers、processors、exporters、service。其中 service.pipelines 定义数据管道，将前三者串联为完整的数据流。

# config.yaml — OpenTelemetry Collector 配置文件结构
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512

exporters:
  otlp:
    endpoint: "gateway.example.com:4317"
    tls:
      insecure: false
  logging:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, logging]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

  配置要点：
  receivers：定义数据入口，支持 OTLP、Jaeger、Prometheus、Kubernetes 等多种协议。
processors：数据加工层，常用处理器包括 batch（批处理）、memory_limiter（内存限流）、filter（过滤）、attributes（属性修改）、span（链路处理）。
exporters：数据出口，支持 OTLP、Prometheus、Jaeger、Kafka、文件等。
service.pipelines：按信号类型（traces / metrics / logs）定义独立管道，每个管道引用对应的 receiver、processor、exporter。

3.3 Receiver / Processor / Exporter 管道详解

管道（Pipeline）是 Collector 的核心抽象。每个管道由三阶段组成：Receiver 接收数据 → Processor 处理数据 → Exporter 导出数据。数据在管道内单向流动，支持多 Receiver 输入、多 Processor 串联、多 Exporter 输出。

3.4 管道配置实战：Agent 模式与 Gateway 模式

以下分别给出 Agent 模式和 Gateway 模式的典型配置片段，展示如何通过 service.pipelines 组织不同信号的数据流。

3.4.1 Agent 模式配置（边缘采集 + 本地缓存）

# agent-config.yaml — Agent 模式：采集 → 本地处理 → 转发至 Gateway
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
  batch:
    timeout: 500ms
    send_batch_size: 512
  attributes:
    actions:
      - key: collector.mode
        value: agent
        action: upsert

exporters:
  otlp:
    endpoint: "gateway.internal:4317"
    tls:
      insecure: true
    sending_queue:
      enabled: true
      num_consumers: 10
      queue_size: 5000
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, attributes, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp]

关键配置说明：

sending_queue：启用发送队列，当 Gateway 不可用时数据暂存内存，队列满后按 backpressure 策略丢弃或阻塞。
retry_on_failure：自动重试，指数退避，最大重试时间 300 秒。配合 Runbook 故障自愈时，建议将重试策略与告警阈值联动。
attributes：为所有数据注入 collector.mode=agent 标签，便于后续在 Gateway 侧做数据源识别。

3.4.2 Gateway 模式配置（聚合 + 多租户 + 导出）

# gateway-config.yaml — Gateway 模式：接收 Agent 数据 → 全局处理 → 导出至后端
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        max_recv_msg_size_mib: 50

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 1024
  batch:
    timeout: 2s
    send_batch_size: 4096
  filter:
    error_mode: ignore
    traces:
      span:
        - 'attributes["http.method"] == "OPTIONS"'
  attributes:
    actions:
      - key: environment
        value: production
        action: upsert

exporters:
  otlp:
    endpoint: "backend.observability:4317"
    tls:
      cert_file: /etc/ssl/certs/client.crt
      key_file: /etc/ssl/private/client.key
    sending_queue:
      enabled: true
      queue_size: 10000
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: otel_gateway

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter, attributes, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, prometheus]

3.5 管道处理顺序与故障自愈关联

Processor 在管道中的执行顺序由配置中的列表顺序决定。在故障自愈场景中，Processor 的编排直接影响数据质量与恢复速度：

memory_limiter 应放在首位：在数据进入任何耗时处理前先做内存限流，防止 OOM 导致 Collector 崩溃。
filter 应放在 batch 之前：先过滤无效数据，减少 batch 的内存占用与网络开销。
attributes 应放在 batch 之前或之后：若需在批处理前注入标签（如来源标识），则放在 batch 前；若需在导出前统一修改，则放在 batch 后。
batch 通常放在最后：批处理将数据合并为更大的批次，提高导出效率。但若后续还有导出前的最后转换（如压缩），则 batch 可放在倒数第二位。

3.6 多管道与信号隔离

Collector 支持按信号类型（traces、metrics、logs）定义独立管道。每个管道拥有独立的 Receiver、Processor、Exporter 链，互不干扰。这种隔离设计在故障自愈中至关重要：

链路数据（traces）：通常需要采样、过滤、属性注入，Processor 链较长。
指标数据（metrics）：对实时性要求高，Processor 链应尽量短，避免延迟。
日志数据（logs）：数据量大，需重点配置 batch 和 memory_limiter，防止背压。

# 多管道配置示例：traces / metrics / logs 各自独立
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter, attributes, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp, prometheus]
      processors: [memory_limiter, batch]
      exporters: [otlp, prometheus]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, logging]

自愈联动提示：在 Runbook 故障自愈场景中，建议为每个管道配置独立的健康检查端点（/health），并在 Gateway 侧按信号类型设置不同的告警阈值。例如：traces 管道延迟超过 10 秒触发告警，metrics 管道延迟超过 5 秒触发告警，日志管道队列积压超过 80% 触发告警。

3.7 本章小结

Agent 模式：部署在数据源侧，轻量、低延迟，适合边缘采集与本地缓存。
Gateway 模式：部署在数据中心，负责聚合、过滤、多租户隔离与后端导出。
配置文件结构：receivers → processors → exporters → service.pipelines，YAML 格式，按信号类型隔离。
管道数据流：Receiver 接收 → Processor 处理（顺序执行）→ Exporter 导出，支持多输入、多输出。
故障自愈关键配置：memory_limiter 防 OOM、sending_queue 防网络中断丢数据、retry_on_failure 自动重试。