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 与上下文传播

传播上下文包含 Trace 标识、当前 Span 标识和采样决定。HTTP 调用通常通过 W3C traceparent 请求头传递;下游服务读取后创建子 Span。日志中的 traceId 用于从日志跳到链路,Span 属性则用于解释耗时、状态和调用对象。

添加追踪依赖与后端

以下依赖片段适用于由 Spring Boot 3 管理版本的 Maven 项目。两个服务都需要加入相同依赖。

xml
<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 并提供查询界面。启动单节点容器:

bash
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

预期输出

text
<CONTAINER_ID>
running

容器 ID 会因环境而不同。Jaeger 此时通过 4318 接收 OTLP HTTP Trace,并通过 16686 提供查询界面;其内存存储适合本地验证,容器删除后链路数据会丢失。

配置两个服务

order-service 使用 8080 端口,并调用 8081 端口的库存服务。下面是其 application.yml:

yaml
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 使用同一追踪配置,只需调整应用名和端口:

yaml
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 和传播请求头缺失。

java
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 的日志。

java
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,随后发送一次订单请求:

bash
curl -i -X POST http://localhost:8080/orders/SKU-1001

预期输出

text
HTTP/1.1 200
Content-Type: application/json

{"sku":"SKU-1001","reserved":true}

两个服务的日志应出现相同的 Trace ID 和不同的 Span ID:

text
[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 已创建,再排查导出链路,避免只盯着查询界面。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现分布式链路追踪

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通