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

3. OpenTelemetry Collector 部署：使用 Docker 部署 OTel Collector，配置基本的 receivers、processors、exporters

OpenTelemetry Collector 是整个可观测性管道的核心组件，负责接收、处理并导出遥测数据。本章将使用 Docker 完成 Collector 的部署，并配置最基础的 receivers（接收器）、processors（处理器） 和 exporters（导出器），为后续接入值班机器人告警事件打下数据管道基础。

前置条件：确保已安装 Docker 20.10+ 和 Docker Compose v2+。建议预留至少 512MB 内存和 1 核 CPU 给 Collector 容器。

3.1 整体架构：Collector 数据管道

Collector 采用 Pipeline（管道）模式，数据依次流经 Receiver → Processor → Exporter。下图展示了本章将部署的 Collector 内部数据流与外部交互关系：

3.2 使用 Docker 部署 OTel Collector

我们采用 Docker Compose 方式部署，便于管理配置挂载和端口映射。首先创建项目目录结构：

mkdir -p otel-collector-demo/config
cd otel-collector-demo

3.2.1 编写 Collector 配置文件

在 config/otel-collector-config.yaml 中写入以下配置。该配置定义了接收 OTLP 和 Prometheus 指标、使用 batch 处理器、并导出到控制台和 OTLP 后端：

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

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

exporters:
  logging:
    loglevel: debug
  otlp:
    endpoint: "jaeger:4317"
    tls:
      insecure: true

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

  配置要点：
  receivers.otlp：同时开启 gRPC (4317) 和 HTTP (4318) 协议，兼容多种 SDK 上报。
processors.batch：将数据分批发送，减少网络开销，timeout 和 send_batch_size 需根据流量调整。
processors.memory_limiter：防止 Collector 内存溢出，limit_mib 建议设为容器内存上限的 70%。
exporters.logging：输出到控制台，调试阶段使用 debug 级别；生产环境建议改为 info。

3.2.2 编写 Docker Compose 文件

在项目根目录创建 docker-compose.yaml：

version: '3.8'

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.102.0
    container_name: otel-collector
    restart: unless-stopped
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "8888:8888"   # Prometheus 自监控指标
      - "8889:8889"   # Collector 健康检查
    volumes:
      - ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml
    command: ["--config=/etc/otel-collector-config.yaml"]
    networks:
      - otel-net

  jaeger:
    image: jaegertracing/all-in-one:1.57
    container_name: jaeger
    restart: unless-stopped
    ports:
      - "16686:16686" # Jaeger UI
      - "4317"        # OTLP gRPC (内部)
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    networks:
      - otel-net

networks:
  otel-net:
    driver: bridge

3.2.3 启动服务

docker compose up -d

验证 Collector 是否正常运行：

# 查看容器日志
docker logs otel-collector --tail 20

# 健康检查端点
curl http://localhost:8889/health

# 自监控指标
curl http://localhost:8888/metrics | head -20

快速验证：如果日志中出现 "Everything is ready. Run the following command to start the collector"，且健康检查返回 {"status":"Server available"}，则部署成功。

3.3 核心组件详解

下表对比了本章配置中涉及的 receivers、processors 和 exporters 的核心参数与用途：

组件类型	组件名称	核心参数	用途说明
Receiver	otlp	`protocols.grpc.endpoint` `protocols.http.endpoint`	接收 OTLP 格式的 traces、metrics、logs
Receiver	prometheus	`config.scrape_configs`	拉取 Prometheus 指标，用于自监控或第三方 exporter
Processor	batch	`timeout` (1s) `send_batch_size` (1024)	合并数据为批次，降低出口请求数
Processor	memory_limiter	`check_interval` (1s) `limit_mib` (512)	内存软限制，达到阈值时降级处理
Exporter	logging	`loglevel` (debug/info)	将数据打印到标准输出，调试首选
Exporter	otlp	`endpoint` `tls.insecure`	转发数据到下游 OTLP 兼容后端（如 Jaeger）

3.4 配置验证与调试

部署完成后，建议执行以下验证步骤，确保管道各环节正常：

检查 Collector 自身指标：访问 http://localhost:8888/metrics，搜索 otelcol_receiver_accepted_spans 和 otelcol_exporter_sent_spans，确认数据流入流出正常。
发送测试 Trace：使用 telemetrygen 工具快速生成测试数据：

docker run --rm --network otel-collector-demo_otel-net \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:0.102.0 \
  traces --otlp-endpoint otel-collector:4317 --duration 5s

查看 Jaeger UI：打开浏览器访问 http://localhost:16686，选择服务 "telemetrygen"，应能看到生成的 Trace 数据。
检查 Collector 日志：执行 docker logs otel-collector --tail 50，确认无 error 级别日志，且能看到 {"kind":"exporter","data_type":"traces","name":"logging"} 的输出。

常见问题：

端口冲突：如果 4317/4318 被占用，修改 docker-compose 中宿主机映射端口，例如 "14317:4317"。
配置文件语法错误：Collector 启动时会校验 YAML 格式，若失败则容器退出。使用 docker compose logs otel-collector 查看具体错误行。
内存限制过小：如果 memory_limiter.limit_mib 设置过低，Collector 会频繁触发降级，导致数据丢失。建议根据实际负载逐步调优。

3.5 生产环境配置建议

本章的配置适用于开发/测试环境。生产部署时，建议进行以下增强：

使用持久化队列：在 exporters 中增加 sending_queue 配置，防止后端短暂不可用时数据丢失。
启用 TLS 认证：为 OTLP receiver 和 exporter 配置 mTLS，保障数据传输安全。
添加资源检测处理器：使用 resourcedetection processor 自动填充容器/主机元数据。
配置多 exporter 负载均衡：对于高吞吐场景，使用 loadbalancing exporter 将数据分发到多个后端。
设置资源限制：在 Docker Compose 中为 Collector 容器添加 deploy.resources.limits，避免占用宿主机全部资源。