OpenTelemetry 接入实战：30 分钟给 Spring Boot 加上全链路追踪
OpenTelemetry Integration: Adding Full Distributed Tracing to Spring Boot in 30 Minutes
| Ryan Zhang | 2026-08-13T08:30:12
分布式追踪听起来复杂，但用 OpenTelemetry 的自动检测，30 分钟就能跑起来。这篇给一个完整的实战教程。
Distributed tracing sounds complex, but OpenTelemetry's auto-instrumentation gets it running in 30 minutes. A complete practical tutorial.
## 为什么需要分布式追踪 微服务架构下，一个请求可能经过 5-10 个服务。出了问题，日志分散在各个服务里，排查起来像大海捞针。 分布式追踪的核心思路：**给每个请求分配一个唯一的 Trace ID，在所有服务之间传递**。这样就能把一个请求经过的所有服务串联起来。 ## 整体架构 ``` Spring Boot App → OTel Java Agent (自动检测) → OTel Collector → Jaeger ``` 我们用 OpenTelemetry 的 Java Agent 做自动检测，零代码侵入。 ## 第一步：部署 Jaeger（5 分钟） ```bash docker run -d --name jaeger -p 16686:16686 \ # Jaeger UI -p 4317:4317 \ # OTLP gRPC -p 4318:4318 \ # OTLP HTTP jaegertracing/all-in-one:latest ``` 打开 `http://localhost:16686` 就能看到 Jaeger 的 UI。 ## 第二步：下载 OTel Java Agent（2 分钟） ```bash wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar ``` 这个 Agent 会自动检测 Spring Boot、HTTP 客户端、数据库驱动、消息队列等 100+ 个库，不需要改任何代码。 ## 第三步：启动应用（3 分钟） ```bash java -javaagent:opentelemetry-javaagent.jar -Dotel.service.name=order-service -Dotel.exporter.otlp.endpoint=http://localhost:4317 -Dotel.traces.sampler=always_on -jar your-app.jar ``` 就这么多。启动后访问几次 API，然后在 Jaeger UI 里就能看到 trace 了。 ## 第四步：自定义 Span（10 分钟） 自动检测已经覆盖了 HTTP 请求、数据库调用、Redis 操作。如果需要追踪自定义的业务逻辑，加几行代码： ```java // 添加依赖 // implementation 'io.opentelemetry:opentelemetry-api' import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.Tracer; import io.opentelemetry.api.GlobalOpenTelemetry; @Service public class OrderService { private final Tracer tracer = GlobalOpenTelemetry.getTracer("order-service"); public Order createOrder(CreateOrderRequest req) { Span span = tracer.spanBuilder("createOrder") .setAttribute("order.amount", req.getAmount()) .setAttribute("order.userId", req.getUserId()) .startSpan(); try (var scope = span.makeCurrent()) { // 业务逻辑 Order order = processOrder(req); span.setAttribute("order.id", order.getId()); return order; } catch (Exception e) { span.recordException(e); span.setStatus(StatusCode.ERROR); throw e; } finally { span.end(); } } } ``` ## 第五步：跨服务传播（10 分钟） 如果有多个服务，每个服务都用 OTel Agent 启动。Trace Context 会通过 HTTP Header 自动传播： ``` order-service → HTTP 请求（带 traceparent header）→ payment-service ``` OTel Agent 自动处理了 context 的注入和提取，不需要手动传 Trace ID。 ### 服务间调用示例 ```java // order-service 调用 payment-service // OTel Agent 自动在 RestTemplate/WebClient 的请求里注入 traceparent header RestTemplate restTemplate = new RestTemplate(); PaymentResult result = restTemplate.postForObject( "http://payment-service/api/pay", payRequest, PaymentResult.class ); ``` 在 Jaeger UI 里，你会看到一个完整的调用链： ``` order-service::POST /api/orders (总耗时 350ms) ├── order-service::MySQL INSERT (15ms) ├── payment-service::POST /api/pay (280ms) │ ├── payment-service::Redis GET (2ms) │ └── payment-service::MySQL UPDATE (8ms) └── order-service::Kafka SEND (5ms) ``` ## 生产环境配置建议 ```bash java -javaagent:opentelemetry-javaagent.jar -Dotel.service.name=order-service -Dotel.exporter.otlp.endpoint=http://otel-collector:4317 -Dotel.traces.sampler=parentbased_traceidratio -Dotel.traces.sampler.arg=0.1 \ # 采样 10% -Dotel.metrics.exporter=prometheus -Dotel.logs.exporter=otlp -jar your-app.jar ``` 关键参数： - **采样率 10%**：生产环境不要 100% 采样，会产生大量数据 - **Metrics 导出到 Prometheus**：复用现有的监控栈 - **Logs 也通过 OTel**：实现 trace-log 关联 ## 排查效果 接入前：某接口偶发超时，排查了两天，翻了五个服务的日志。 接入后：在 Jaeger 找到一条慢 trace，直接看到是 payment-service 调用第三方支付网关超时。5 分钟定位问题。 分布式追踪不是"高大上"的东西，30 分钟就能跑起来，收益是实打实的。
Complete 30-minute tutorial for adding distributed tracing to Spring Boot using OpenTelemetry: deploy Jaeger (5min), download OTel Java Agent (2min), start app with agent flags (3min), add custom spans for business logic (10min), cross-service trace propagation via automatic header injection (10min). Production tips: 10% sampling rate, Prometheus metrics export, trace-log correlation.