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

4. 环境准备：安装 OpenTelemetry Collector、配置 OTLP Receiver、部署 Demo 流水线应用

本章是课程动手实践的基础环节。你将完成三件事：安装 OpenTelemetry Collector 二进制或容器实例、配置 OTLP Receiver 作为数据入口、部署一个模拟 CI/CD 流水线行为的 Demo 应用。完成本环境后，后续章节的所有指标采集、处理和导出实验都将基于此环境运行。

4.1 整体架构概览

下图展示了本章完成后本地环境的核心组件关系：Demo 应用通过 OTLP 协议将流水线性能指标发送给 Collector，Collector 通过 OTLP Receiver 接收后暂存于内存队列，后续可转发至后端分析平台。

4.2 安装 OpenTelemetry Collector

推荐使用 opentelemetry-collector-contrib 发行版，它包含 OTLP Receiver 及后续实验所需的众多处理器和导出器。以下提供两种安装方式：二进制直接安装和 Docker 容器化部署。

4.2.1 二进制安装（Linux / macOS）

# 下载最新 contrib 发行版（以 v0.108.0 为例）
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.108.0/otelcol-contrib_0.108.0_linux_amd64.tar.gz

# 解压并移动到系统路径
tar -xzf otelcol-contrib_0.108.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/otelcol-contrib

# 验证安装
otelcol-contrib --version

4.2.2 Docker 容器化部署

# 拉取 contrib 镜像
docker pull otel/opentelemetry-collector-contrib:0.108.0

# 创建配置目录
mkdir -p /etc/otelcol-contrib

建议： 课程实验推荐使用 Docker 方式，便于快速重置环境。生产环境则建议使用 systemd 管理二进制进程。

4.3 配置 OTLP Receiver

Collector 的核心行为由 YAML 配置文件驱动。以下是最简配置，仅启用 OTLP Receiver 和一个调试导出器（用于验证数据到达）。

4.3.1 创建配置文件

在 /etc/otelcol-contrib/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

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

4.3.2 配置关键参数说明

配置项	值	说明
`receivers.otlp.protocols.grpc.endpoint`	`0.0.0.0:4317`	gRPC 协议监听地址，Demo 应用默认使用此端口
`receivers.otlp.protocols.http.endpoint`	`0.0.0.0:4318`	HTTP/Protobuf 协议监听地址，备用传输方式
`processors.batch.timeout`	`1s`	数据在内存队列中最多等待 1 秒后打包发送
`exporters.debug.verbosity`	`detailed`	将接收到的指标完整打印到标准输出，用于验证

4.3.3 启动 Collector

# Docker 方式启动（推荐）
docker run -d --name otel-collector \
  -p 4317:4317 -p 4318:4318 \
  -v /etc/otelcol-contrib/config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:0.108.0

# 二进制方式启动
otelcol-contrib --config /etc/otelcol-contrib/config.yaml

端口冲突检查： 确保 4317 和 4318 端口未被占用。可使用 netstat -tulpn | grep -E '4317|4318' 检查。若冲突，修改配置中的 endpoint 端口号。

4.4 部署 Demo 流水线应用

Demo 应用是一个轻量级 Python 程序，模拟 CI/CD 流水线的三个阶段：代码构建（Build）、单元测试（Test）和环境部署（Deploy）。每个阶段会生成对应的性能指标（如执行耗时、状态计数）并通过 OTLP 协议发送给 Collector。

4.4.1 应用代码结构

demo-pipeline/
├── main.py              # 主入口，模拟流水线执行
├── pipeline_stages.py   # 各阶段逻辑与指标生成
├── otlp_exporter.py     # OTLP 指标导出封装
├── requirements.txt     # 依赖：opentelemetry-api, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-grpc
└── run.sh               # 启动脚本

4.4.2 核心依赖安装

pip install opentelemetry-api \
            opentelemetry-sdk \
            opentelemetry-exporter-otlp-proto-grpc

4.4.3 启动 Demo 应用

# 克隆或复制 demo-pipeline 目录到本地
cd demo-pipeline

# 赋予执行权限并运行
chmod +x run.sh
./run.sh

应用启动后，会每隔 10 秒自动执行一轮流水线模拟，并向 localhost:4317 发送指标数据。

4.5 验证数据流是否正常

完成上述步骤后，通过以下方式确认数据已成功到达 Collector。

4.5.1 查看 Collector 日志

# Docker 方式
docker logs -f otel-collector

# 二进制方式（前台运行直接查看终端输出）

正常输出应包含类似以下内容：

Metric #0
Descriptor:
  -> Name: pipeline.build.duration
  -> Description: Duration of build stage
  -> Unit: ms
  -> DataType: Histogram
...
Timestamp: 2025-01-15 10:23:45 +0000 UTC
Value: 1234.56

4.5.2 使用 curl 检查 OTLP HTTP 端点

# 发送空请求测试端点是否存活（预期返回 200）
curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/x-protobuf" \
  --data-binary '' 2>/dev/null || echo "Endpoint is alive (empty request rejected as expected)"

  验证清单：
  Collector 进程运行中，无崩溃或端口绑定错误。
Demo 应用日志显示“Metrics exported successfully”。
Collector 日志中出现以 Metric #0 开头的指标打印块。

4.6 环境准备清单

组件	状态	验证方式
OpenTelemetry Collector	已安装并运行	`docker ps` 或 `ps aux \| grep otelcol`
OTLP Receiver 配置	已加载且监听 4317/4318	`netstat -tulpn \| grep -E '4317\|4318'`
Demo 流水线应用	已启动并发送指标	Collector 日志中出现指标数据