📚 课程目录第4章环境准备

4. 环境准备

本章将完成监控链路的核心基础设施搭建。你需要依次安装 OpenTelemetry Collector（数据采集与转发）、配置 OTLP Receiver（接收来自 CI/CD 流水线的遥测数据），并部署 Jaeger（分布式追踪存储与 UI）和 Prometheus（指标存储与告警）作为后端系统。以下步骤均以 Linux 环境为例，使用 Docker 与二进制文件混合部署方式。

4.1 整体架构概览

下图展示了本章完成后，CI/CD 流水线产生的追踪（Traces）与指标（Metrics）数据的流向：

部署顺序建议：先启动 Jaeger 和 Prometheus 后端，再启动 OpenTelemetry Collector，最后配置 CI/CD 流水线发送数据。这样可以避免 Collector 启动时因后端不可用而报错。

4.2 安装 OpenTelemetry Collector

OpenTelemetry Collector 是一个与供应商无关的代理，负责接收、处理和导出遥测数据。我们使用 OTLP Receiver 接收来自流水线的数据，并配置导出器将数据转发给 Jaeger 和 Prometheus。

4.2.1 下载与启动 Collector

推荐使用官方预编译的二进制文件或 Docker 镜像。以下为 Docker 部署方式：

# 拉取 OpenTelemetry Collector Contrib 发行版（包含更多组件）
docker pull otel/opentelemetry-collector-contrib:0.102.0

# 创建配置文件目录
mkdir -p /etc/otel-collector

4.2.2 配置文件：config.yaml

在 /etc/otel-collector/config.yaml 中写入以下配置。该配置启用了 OTLP Receiver（gRPC 和 HTTP），并设置了 Jaeger 和 Prometheus 导出器。

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

exporters:
  jaeger:
    endpoint: "jaeger:14250"
    tls:
      insecure: true
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: "cicd_pipeline"

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

  关键参数说明：
  receivers.otlp.protocols：同时开启 gRPC (4317) 和 HTTP (4318) 端口，兼容不同语言的 SDK。
exporters.jaeger.endpoint：指向 Jaeger 的 gRPC 端口（14250），确保网络互通。
exporters.prometheus.namespace：为所有指标添加前缀，便于在 Prometheus 中区分。
processors.batch：启用批处理，减少网络开销，提升吞吐量。

4.2.3 启动 Collector 容器

docker run -d --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8889:8889 \
  -v /etc/otel-collector/config.yaml:/etc/otel-collector-config.yaml \
  otel/opentelemetry-collector-contrib:0.102.0 \
  --config /etc/otel-collector-config.yaml

端口冲突检查：确保 4317、4318、8889 端口未被占用。如果主机上已运行 Prometheus 或 Jaeger，请调整 Collector 的导出器端口或使用不同网络命名空间。

4.3 配置 OTLP Receiver 详解

OTLP Receiver 是 Collector 的入口组件，负责接收符合 OpenTelemetry 协议（OTLP）的数据。CI/CD 流水线中的 SDK 或自动注入工具会通过 gRPC 或 HTTP 将 Span 和 Metric 发送到此 Receiver。

协议	默认端口	传输格式	适用场景
gRPC	4317	Protobuf (二进制)	高性能、低延迟，推荐生产环境
HTTP	4318	JSON / Protobuf	调试、浏览器端、防火墙友好

在 Collector 配置中，你可以通过 receivers.otlp.protocols 同时启用两者，SDK 会自动选择最优协议。如果流水线运行在 Kubernetes 集群中，建议使用 gRPC 以获得更好的性能。

4.4 部署 Jaeger（分布式追踪后端）

Jaeger 用于接收、存储和查询来自 Collector 的追踪数据。我们部署 All-in-One 模式（包含 Agent、Collector、Query 和 UI），适合开发和测试环境。

4.4.1 Docker 部署 Jaeger

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 14250:14250 \
  -p 14269:14269 \
  jaegertracing/all-in-one:1.57

端口	用途	说明
16686	Jaeger UI	浏览器访问追踪查询界面
14250	gRPC 接收	Collector 通过此端口发送追踪数据
14269	管理端口	健康检查与指标暴露

4.4.2 验证 Jaeger 启动

访问 http://<主机IP>:16686，如果看到 Jaeger UI 界面，说明部署成功。此时还没有数据，后续章节配置流水线后即可看到追踪。

4.5 部署 Prometheus（指标后端）

Prometheus 负责抓取 Collector 暴露的指标数据，并提供强大的 PromQL 查询和告警能力。

4.5.1 准备 Prometheus 配置文件

创建 /etc/prometheus/prometheus.yml：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'otel-collector'
    static_configs:
      - targets: ['otel-collector:8889']
        labels:
          application: 'cicd-pipeline'

注意：如果 Prometheus 与 Collector 运行在同一台主机上，可以将 otel-collector:8889 替换为 localhost:8889。如果使用 Docker Compose，请确保服务名正确。

4.5.2 Docker 部署 Prometheus

docker run -d --name prometheus \
  -p 9090:9090 \
  -v /etc/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus:v2.52.0

4.5.3 验证 Prometheus 启动

访问 http://<主机IP>:9090，在 Status → Targets 页面中查看 otel-collector 任务是否处于 UP 状态。如果显示 UP，说明 Prometheus 已成功从 Collector 抓取指标。

4.6 组件连通性验证

部署完成后，建议执行以下快速验证步骤，确保各组件之间通信正常：

检查 Collector 日志： docker logs otel-collector，确认无连接拒绝或超时错误。
测试 Jaeger 端口： telnet <主机IP> 14250，确认端口可达。
测试 Prometheus 抓取： 访问 http://<主机IP>:9090/api/v1/targets，查看 otel-collector 的 health 字段。
发送测试数据（可选）： 使用 telemetrygen 工具发送模拟追踪和指标，验证端到端链路。

  常见问题排查：
  Collector 无法连接 Jaeger： 检查 Jaeger 容器是否运行，以及 jaeger:14250 是否可解析。Docker 中可使用 --link 或自定义网络。
Prometheus 抓取失败： 确认 Collector 的 exporters.prometheus.endpoint 配置为 0.0.0.0:8889，而非 localhost:8889，否则容器外无法访问。
端口被占用： 使用 netstat -tulpn | grep <端口号> 查找占用进程，或修改映射端口。

4.7 本章小结

至此，你已经完成了以下核心组件的安装与配置：

OpenTelemetry Collector：配置了 OTLP Receiver（gRPC + HTTP），并设置了 Jaeger 和 Prometheus 导出器。
Jaeger：All-in-One 模式部署，提供追踪存储与 UI。
Prometheus：配置了抓取任务，指向 Collector 的指标端点。