OpenTelemetry分布式链路追踪服务器集群

当你管理的服务从单机变成集群，一个请求经过多个节点后出了问题，靠日志一个个翻效率太低。OpenTelemetry分布式链路追踪能帮你把跨服务的调用链串起来，快速定位瓶颈和异常。
本文面向零基础用户，用最直白的步骤教你在一组服务器上搭建起完整的追踪体系。

动手前要准备什么

• 至少两台 Linux 服务器（我以 Ubuntu 22.04 为例），内网互通且能访问外网。
• 每台服务器安装 Docker 和 docker-compose（版本不限，建议 20.10 以上）。
• 服务器时间已同步（用 timedatectl 检查，最好打开 NTP）。
• 准备好一个演示应用（Java 或 Python 都可，本文用 Spring Boot 示例）。

如果你只有单台服务器，也可以把 Collector 和 Jaeger 都装在同一台，但集群环境至少需要两台才能体现追踪的价值。

部署 OpenTelemetry Collector（采集端）

选择一台服务器作为 Collector 节点，负责接收应用上报的 Trace 数据并转发给后端存储（这里用 Jaeger）。

1. 创建目录并把下面的内容写进 otel-collector-config.yaml：

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

exporters:
  jaeger:
    endpoint: "http://你的Jaeger地址:14250"
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]

注意：endpoint 填 Jaeger 服务器的 IP 和端口，如果 Jaeger 和 Collector 在同一台，可以用 localhost。

1. 编写 docker-compose.yml：

version: '3'
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    ports:
      - "4317:4317"
      - "4318:4318"

1. 启动 Collector：

docker-compose up -d

验证是否启动成功：docker-compose logs 看到 Everything is ready 就说明 Collector 正常工作了。

在应用中接入 OpenTelemetry

以 Java Spring Boot 应用为例，只需两步即可让应用把 Trace 发给 Collector。

1. 下载 OpenTelemetry Java Agent：在你的应用服务器上执行

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

1. 启动应用时添加 JVM 参数，指定 Collector 地址：

java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.service.name=my-demo-service \
     -Dotel.exporter.otlp.endpoint=http://Collector服务器IP:4317 \
     -jar my-application.jar

如果你的应用跑在其他集群节点上，只要网络能到达 Collector 的 4317 端口即可，不需要在每个节点都装 Collector。

避坑指南与常见问题

端口冲突：Collector 默认占用 4317/4318，检查一下 docker 映射是否被其他服务占用。

数据量过大：如果不设置采样率，高并发下会产生大量数据。
推荐在生产环境使用概率采样：在 Collector 配置的 processors 中添加 batch 和 memory_limiter，并设置采样率（例如 10%）。

网络不通：检查各节点之间的防火墙，确保 Collector 端口（4317/4318）和 Jaeger 端口（14250）都能互相访问。

Agent 版本不匹配：Java Agent 版本建议与 Collector 版本对应，否则可能出现协议不兼容报错。

验证链路追踪效果

1. 在另一台服务器启动 Jaeger（最简单的 Docker 方式）：

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

1. 访问 http://Jaeger服务器IP:16686，打开 Jaeger UI。
2. 调用你的演示应用几次（比如访问一个带数据库查询的接口）。
3. 在 Jaeger UI 左侧 Service 下拉框选择 my-demo-service，点击“Find Traces”，就能看到请求的完整调用链。

如果没数据，先确认应用日志是否有 WARN 信息（常见为 Agent 连不上 Collector），再检查 Collector 的日志是否收到数据。

如果你正在处理 OpenTelemetry分布式链路追踪服务器集群，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。
熟练掌握后，还可以进一步配置其他 Exporter（如 Prometheus）和采样策略，打造更完整的可观测性体系。