4. OpenTelemetry Collector 安装与配置：Docker 部署、基本配置文件结构、Pipeline 概念

OpenTelemetry Collector 是整个可观测性架构的“数据平面”核心组件。它负责接收、处理、导出遥测数据（Trace、Metric、Log），并支持多种协议和格式。本章将围绕 Collector 的 Docker 部署、配置文件结构以及 Pipeline 概念展开，帮助你快速搭建生产级数据采集管道。

4.1 为什么需要 OpenTelemetry Collector？

在微服务架构中，每个服务直接向后端发送遥测数据会导致以下问题：

  • 耦合性高：服务 SDK 需要硬编码后端地址和认证信息。
  • 资源浪费：每个服务独立维护连接池和重试逻辑。
  • 数据格式不统一：不同语言 SDK 可能产生不同协议的数据。
  • 缺乏中间处理能力：无法在数据到达后端前进行过滤、采样、脱敏。

Collector 作为独立代理层，解耦了数据生产与消费，并提供统一的处理能力。

4.2 Docker 部署 Collector

使用 Docker 是快速启动 Collector 的最简方式。以下步骤适用于开发环境与生产环境的最小化部署。

4.2.1 拉取镜像

docker pull otel/opentelemetry-collector-contrib:latest
镜像选择说明： opentelemetry-collector-contrib 包含社区贡献的扩展组件（如 Kafka 接收器、Prometheus 导出器），推荐用于生产环境。若仅需核心组件，可使用 opentelemetry-collector 镜像。

4.2.2 准备配置文件

在宿主机创建目录 /etc/otel-collector，并写入 config.yaml：

mkdir -p /etc/otel-collector
cat << 'EOF' > /etc/otel-collector/config.yaml
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

exporters:
  debug:
    verbosity: detailed
  otlp:
    endpoint: "jaeger:4317"
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, otlp]
EOF

4.2.3 启动容器

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -v /etc/otel-collector/config.yaml:/etc/otel-collector-config.yaml \
  otel/opentelemetry-collector-contrib:latest \
  --config /etc/otel-collector-config.yaml
端口映射注意： 4317 用于 gRPC 协议，4318 用于 HTTP 协议。如果宿主机已有服务占用这些端口，请修改映射或调整 Collector 配置中的 endpoint。

4.3 基本配置文件结构

Collector 配置文件采用 YAML 格式，由四个顶级区块组成：

区块 作用 示例组件
receivers 定义数据接收方式与端口 otlp, jaeger, prometheus, kafka
processors 对数据进行过滤、采样、转换、批处理 batch, memory_limiter, filter, attributes
exporters 定义数据发送目标 debug, otlp, prometheus, loki, elasticsearch
service.pipelines 将 receivers、processors、exporters 串联成完整管道 traces, metrics, logs

4.3.1 典型配置示例（含多管道）

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
  prometheus:
    config:
      scrape_configs:
        - job_name: 'otel-collector'
          scrape_interval: 10s
          static_configs:
            - targets: ['0.0.0.0:8888']

processors:
  batch:
    timeout: 2s
    send_batch_size: 2048
  memory_limiter:
    check_interval: 1s
    limit_mib: 512

exporters:
  debug:
    verbosity: normal
  otlp:
    endpoint: "backend.example.com:4317"
    tls:
      insecure: false
      ca_file: /etc/ssl/certs/ca-certificates.crt

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

4.4 Pipeline 概念

Pipeline 是 Collector 的核心抽象，定义了数据从接收到导出的完整路径。每个 Pipeline 由三部分构成：

  • Receivers：数据入口，一个 Pipeline 可以包含多个 Receiver。
  • Processors：数据处理链，按配置顺序依次执行。可以为空。
  • Exporters：数据出口，一个 Pipeline 可以包含多个 Exporter（扇出）。

Collector 支持三种独立的 Pipeline 类型：traces、metrics、logs。它们之间互不干扰，但可以共享相同的 Receiver 或 Exporter 实例。

Pipeline 数据流原则： 数据在 Pipeline 内是单向流动的：Receiver → Processor(s) → Exporter(s)。Processor 的执行顺序由配置中的列表顺序决定，不支持条件分支或循环。

4.5 Pipeline 数据流架构图

下图展示了 Collector 内部一个典型 Trace Pipeline 的数据流向：

OpenTelemetry Collector Pipeline 数据流 Collector Pipeline 数据流（Traces） 微服务 A OTLP gRPC 微服务 B OTLP HTTP Receiver otlp gRPC :4317 HTTP :4318 协议解析 Processor memory_limiter batch 过滤/采样 属性修改 Exporter debug otlp Jaeger 后端 数据流方向：微服务 → Receiver（协议解析） → Processor（批处理/过滤） → Exporter（发送至后端） Pipeline 内数据单向流动，Processor 按配置顺序执行，支持多个 Exporter 扇出

4.6 多 Pipeline 与数据隔离

在实际部署中，通常需要同时处理 Trace、Metric、Log 三种数据类型。Collector 允许为每种数据类型定义独立的 Pipeline，实现数据隔离和差异化处理：

Pipeline 名称 典型 Receiver 典型 Processor 典型 Exporter
traces otlp, jaeger, zipkin batch, memory_limiter, tail_sampling otlp, jaeger, debug
metrics otlp, prometheus, hostmetrics batch, filter, metricstransform otlp, prometheus, debug
logs otlp, filelog, syslog batch, filter, logstransform otlp, loki, elasticsearch, debug
最佳实践： 生产环境中建议为 traces 和 metrics 分别配置独立的 Pipeline，并启用 memory_limiter 处理器防止 Collector OOM。对于日志量大的场景，可单独部署一个 Collector 实例专门处理 logs。

4.7 验证 Collector 是否正常工作

启动 Collector 后，可以通过以下方式验证：

  1. 查看日志：docker logs otel-collector，确认无错误信息。
  2. 健康检查端点：curl http://localhost:13133，返回 {"status":"Server is ready."}。
  3. 发送测试数据：使用 telemetrygen 工具发送模拟 Trace：
docker run --rm -it \
  --network host \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest \
  traces --otlp-insecure --duration 5s --rate 10

如果 Collector 配置了 debug exporter，你将在 Collector 日志中看到类似以下输出：

2025/01/15 10:30:45 TracesExporter: 10 spans exported
Span #0
    Trace ID       : 1234567890abcdef1234567890abcdef
    Span ID        : abcdef1234567890
    Name           : /api/v1/users
    Kind           : SPAN_KIND_SERVER
    Start time     : 2025-01-15 10:30:45.123 +0000 UTC
    End time       : 2025-01-15 10:30:45.456 +0000 UTC
    Status code    : Unset

4.8 常见问题与避坑指南

避坑 1：端口冲突 如果 Collector 与 Jaeger 或 Prometheus 部署在同一台机器，注意 4317/4318 端口不要被其他服务占用。建议使用 Docker 网络隔离或修改默认端口。
避坑 2：TLS 配置 生产环境必须启用 TLS。如果后端使用自签名证书，需要将 CA 证书挂载到容器内，并在 exporter 中配置 ca_file 路径。
避坑 3：内存限制 不配置 memory_limiter 处理器时，Collector 可能因突发流量导致 OOM 被 Docker 杀死。建议始终配置该处理器，并设置合理的 limit_mib 值（通常为容器内存限制的 80%）。

4.9 本章小结

通过本章学习，你已掌握：

  • 使用 Docker 快速部署 OpenTelemetry Collector。
  • 理解 YAML 配置文件的四大区块：receivers、processors、exporters、service.pipelines。
  • 掌握 Pipeline 概念及其单向数据流模型。
  • 能够配置多 Pipeline 实现 Trace/Metric/Log 的独立处理。
  • 学会验证 Collector 是否正常工作。
← 上一章 📖 返回目录 下一章 →