4. 环境搭建：安装 OTel Collector、配置本地 Mock 端点、验证连通性

本章是实战课程的基石。我们将完成三件事：在本地环境中安装 OpenTelemetry Collector，配置 Collector 将数据转发到本地 Mock 端点，最后通过发送测试数据验证整条链路是否打通。完成本章后，你将拥有一个可重复使用的本地可观测性沙箱环境。

4.1 安装 OTel Collector

OpenTelemetry Collector 是一个与厂商无关的代理，负责接收、处理和导出遥测数据。我们选择 OTel Collector Contrib 发行版，因为它包含了更丰富的处理器和扩展组件，适合 Mock 隔离场景。

4.2 配置本地 Mock 端点

Mock 端点用于模拟真实后端（如 Jaeger、Prometheus 或云厂商），接收 Collector 导出的数据但不做持久化存储。我们使用 HTTP 文件导出器 + 本地文件接收器 的组合，将数据写入本地 JSON 文件，方便后续断言和验证。

创建配置文件 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:
  # Mock 端点：将数据写入本地文件
  file:
    path: ./mock-data/traces.json
    rotation:
      max_megabytes: 10
      max_days: 1
  # 同时输出到控制台便于实时观察
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [file, debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [file, debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [file, debug]

4.3 启动 Collector 并验证连通性

启动 Collector 前，先创建数据目录：

mkdir -p ./mock-data
otelcol-contrib --config ./otel-collector-config.yaml

启动成功后，终端应显示类似日志：

2024/01/15 10:00:00 INFO    service/telemetry.go:85  Setting up own telemetry...
2024/01/15 10:00:01 INFO    service/telemetry.go:205  Serving Prometheus metrics  {"address": ":8888"}
2024/01/15 10:00:01 INFO    service/service.go:100  Everything is ready. Begin running.

接下来，使用 telemetrygen 工具发送一条测试 Trace 到 Collector：

telemetrygen traces --otlp-insecure --duration 1s --rate 1

检查本地 Mock 文件是否收到数据：

cat ./mock-data/traces.json | head -20

如果看到包含 resourceSpans 或 scopeSpans 的 JSON 结构，说明连通性验证通过。

4.4 整体架构图

下图展示了本章搭建的本地 Mock 隔离环境的数据流：

4.5 验证清单

完成环境搭建后，请逐项确认以下检查点：