4. 部署 OpenTelemetry Collector：Docker 部署、Kubernetes 部署、配置文件结构、Pipeline 配置

OpenTelemetry Collector 是数据管道的核心组件，负责接收、处理、导出遥测数据。本章将覆盖 Collector 的两种主流部署方式、配置文件的结构化设计以及 Pipeline 的声明式配置。掌握这些内容后，你可以在任何环境中快速搭建生产级的数据采集层。

4.1 部署方式对比

根据基础设施类型，Collector 通常以 Docker 容器 或 Kubernetes DaemonSet/Deployment 形式运行。下表从运维维度对比两种方式的关键差异：

4.2 Docker 部署 Collector

使用 Docker 部署 Collector 是最直接的入门方式。以下步骤演示如何快速启动一个完整的 Collector 实例：

1. 拉取镜像：docker pull otel/opentelemetry-collector-contrib:latest
2. 准备配置文件：创建 otel-collector-config.yaml
3. 启动容器：挂载配置文件并映射端口

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8888:8888 \
  -p 8889:8889 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
  otel/opentelemetry-collector-contrib:latest \
  --config=/etc/otel-collector-config.yaml

端口说明：

• 4317：gRPC 接收 OTLP 数据
• 4318：HTTP 接收 OTLP 数据
• 8888：Prometheus 指标暴露端口（Collector 自身指标）
• 8889：健康检查端点

4.3 Kubernetes 部署 Collector

在 Kubernetes 中，推荐使用 OpenTelemetry Operator 或手动编写 YAML 清单。以下是一个典型的 DaemonSet 部署示例：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: otel-collector-agent
  namespace: observability
spec:
  selector:
    matchLabels:
      app: otel-collector-agent
  template:
    metadata:
      labels:
        app: otel-collector-agent
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:latest
        args:
          - "--config=/conf/otel-collector-config.yaml"
        ports:
          - containerPort: 4317
            name: otlp-grpc
          - containerPort: 4318
            name: otlp-http
          - containerPort: 8888
            name: metrics
        volumeMounts:
          - name: collector-config
            mountPath: /conf
      volumes:
        - name: collector-config
          configMap:
            name: otel-collector-config

4.4 配置文件结构

Collector 的配置文件采用 YAML 格式，由四个顶级区块组成。理解每个区块的作用是配置 Pipeline 的前提。

每个区块的职责：

• receivers：定义如何接收数据，例如 otlp、prometheus、jaeger、filelog。
• processors：对数据进行处理，包括批处理、采样、属性修改、过滤等。
• exporters：定义数据输出目标，例如 otlp、prometheusremotewrite、logging。
• extensions：提供 Collector 自身的运维能力，如健康检查、性能分析。
• service.pipelines：将 receivers、processors、exporters 串联成完整的数据流。

4.5 Pipeline 配置详解

Pipeline 是 Collector 的核心抽象。每个 Pipeline 对应一种信号类型（traces / metrics / logs），并声明数据从接收到导出的完整路径。以下是一个生产级 Pipeline 配置示例：

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
    spike_limit_mib: 128
  attributes:
    actions:
      - key: environment
        value: "production"
        action: upsert

exporters:
  otlp:
    endpoint: "backend-collector.observability:4317"
    tls:
      insecure: true
  logging:
    loglevel: debug

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

4.6 Pipeline 数据流可视化

下图展示了一个完整的 traces Pipeline 数据流，从应用 SDK 发送 OTLP 数据开始，经过 Collector 内部处理，最终导出到后端存储：

4.7 配置最佳实践