Java 后端 / 系统课时
实现分布式链路追踪
实现分布式链路追踪
本课为两个 Spring Boot 3 服务接入 Micrometer Tracing 与 OpenTelemetry,通过 OTLP 将链路发送到 Jaeger,并用一次订单调用验证同一 Trace 下的服务端 Span、客户端 Span、自定义业务 Span 及上下文传播。
学习目标
- 区分 Trace、Span、父子关系和传播上下文
- 配置 Micrometer Tracing、OpenTelemetry OTLP 导出与采样
- 使用自动配置的 HTTP 客户端传播上下文,并创建低基数业务 Span
Trace、Span 与上下文传播
Trace 表示一次请求跨越多个组件的完整路径,通常由同一个 traceId 串联。Span 表示其中一个有开始时间、结束时间和状态的工作单元,例如接收 HTTP 请求、调用库存服务或执行库存预留。子 Span 通过父 Span 标识形成调用树。

传播上下文包含 Trace 标识、当前 Span 标识和采样决定。HTTP 调用通常通过 W3C traceparent 请求头传递;下游服务读取后创建子 Span。日志中的 traceId 用于从日志跳到链路,Span 属性则用于解释耗时、状态和调用对象。
添加追踪依赖与后端
以下依赖片段适用于由 Spring Boot 3 管理版本的 Maven 项目。两个服务都需要加入相同依赖。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>本地练习使用 Jaeger 接收 OTLP Trace 并提供查询界面。启动单节点容器:
docker run -d --name jaeger -p 16686:16686 -p 4318:4318 cr.jaegertracing.io/jaegertracing/jaeger:2.20.0
docker inspect -f '{{.State.Status}}' jaeger预期输出
<CONTAINER_ID>
running容器 ID 会因环境而不同。Jaeger 此时通过 4318 接收 OTLP HTTP Trace,并通过 16686 提供查询界面;其内存存储适合本地验证,容器删除后链路数据会丢失。
配置两个服务
order-service 使用 8080 端口,并调用 8081 端口的库存服务。下面是其 application.yml:
spring:
application:
name: order-service
server:
port: 8080
inventory:
base-url: http://localhost:8081
management:
tracing:
sampling:
probability: 1.0
otlp:
tracing:
endpoint: http://localhost:4318/v1/traces
logging:
pattern:
correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "inventory-service 使用同一追踪配置,只需调整应用名和端口:
spring:
application:
name: inventory-service
server:
port: 8081
management:
tracing:
sampling:
probability: 1.0
otlp:
tracing:
endpoint: http://localhost:4318/v1/traces
logging:
pattern:
correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "采样概率 1.0 便于本地看到每次请求。生产环境应根据吞吐量、存储成本和排障要求降低比例,并保留错误、慢请求或重要业务的定向采样策略。
实现跨服务调用
订单服务必须通过 Spring Boot 自动配置的 RestClient.Builder 创建客户端。直接 new RestClient 或自行构造未接入观察能力的客户端,可能导致客户端 Span 和传播请求头缺失。
package com.example.order;
import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClient;
import java.util.Map;
import java.util.Objects;
@RestController
@RequestMapping("/orders")
public class OrderController {
private static final Logger log = LoggerFactory.getLogger(OrderController.class);
private final RestClient inventoryClient;
private final ObservationRegistry observationRegistry;
public OrderController(
RestClient.Builder builder,
ObservationRegistry observationRegistry,
@Value("${inventory.base-url}") String inventoryBaseUrl) {
this.inventoryClient = builder.baseUrl(inventoryBaseUrl).build();
this.observationRegistry = observationRegistry;
}
@PostMapping("/{sku}")
public Map<String, Object> create(@PathVariable String sku) {
return Observation.createNotStarted("order.reserve-stock", observationRegistry)
.lowCardinalityKeyValue("operation", "reserve")
.observe(() -> {
log.info("Creating order for sku={}", sku);
InventoryResponse inventory = inventoryClient.post()
.uri("/inventory/{sku}/reserve", sku)
.retrieve()
.body(InventoryResponse.class);
Objects.requireNonNull(inventory, "Inventory response must not be null");
return Map.of("sku", sku, "reserved", inventory.reserved());
});
}
public record InventoryResponse(boolean reserved) {
}
}库存服务提供被调用接口,并输出一条可用于核对 Trace 的日志。
package com.example.inventory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/inventory")
public class InventoryController {
private static final Logger log = LoggerFactory.getLogger(InventoryController.class);
@PostMapping("/{sku}/reserve")
public InventoryResponse reserve(@PathVariable String sku) {
log.info("Reserving inventory for sku={}", sku);
return new InventoryResponse(true);
}
public record InventoryResponse(boolean reserved) {
}
}operation=reserve 的取值集合固定,适合作为低基数属性。不要把 sku、订单号或用户 ID 直接作为低基数标签,否则会扩大指标和追踪后端的索引规模;需要定位单笔请求时,可将业务 ID 放入日志或受控的 Span 属性,并设置保留策略。
运行并验证完整 Trace
先启动 inventory-service,再启动 order-service,随后发送一次订单请求:
curl -i -X POST http://localhost:8080/orders/SKU-1001预期输出
HTTP/1.1 200
Content-Type: application/json
{"sku":"SKU-1001","reserved":true}两个服务的日志应出现相同的 Trace ID 和不同的 Span ID:
[order-service,<TRACE_ID>,<ORDER_SPAN_ID>] Creating order for sku=SKU-1001
[inventory-service,<TRACE_ID>,<INVENTORY_SPAN_ID>] Reserving inventory for sku=SKU-1001<TRACE_ID> 在上下游保持一致,两个 <SPAN_ID> 应不同。打开 Jaeger 查询界面,选择 order-service 后应找到一条包含订单服务端 Span、自定义 order.reserve-stock Span、HTTP 客户端 Span 和库存服务端 Span 的 Trace。OTLP 批量导出可能有短暂延迟。
传播失败的定位顺序
下游出现新 Trace 而不是子 Span 时,先确认客户端由自动配置的 RestClient.Builder、RestTemplateBuilder 或 WebClient.Builder 创建;再抓取请求头,检查是否存在 traceparent;最后核对网关、消息中间件或自定义拦截器是否删除了传播头。
日志没有 Trace ID 时,检查当前日志是否运行在有效 Span 作用域内,以及相关工作是否切换到未传播上下文的自定义线程池。异步任务、消息消费和手动创建线程需要使用框架已接入观察能力的执行器,或显式捕获并恢复上下文。
Jaeger 没有数据时,依次检查采样概率、应用到 4318 端口的网络、OTLP 端点路径和应用导出日志。先确认 Span 已创建,再排查导出链路,避免只盯着查询界面。