首页 › Spring Cloud › 链路追踪

微服务架构中一个请求经过多个服务，需要通过链路追踪来排查问题。

Micrometer Tracing

Spring Boot 3.x 推荐使用 Micrometer Tracing（取代旧的 Sleuth）。

添加依赖

<!-- Micrometer Tracing + Zipkin -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-reporter-brave</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

配置

# 所有微服务都需要配置
spring:
  application:
    name: user-service             # 服务名（重要，Trace 中标识来源）

management:
  tracing:
    sampling:
      probability: 1.0             # 采样率（生产环境 0.1 即可）
    propagation:
      type: w3c                    # 传播类型（w3c / b3）

  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans  # Zipkin 地址

Zipkin 安装

docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin:latest

# 访问 http://localhost:9411

TraceId 自动注入日志

配置后，日志自动包含 TraceId：

logging:
  pattern:
    level: "%5p [%X{traceId:-},%X{spanId:-}]"

# 原日志
2026-05-15 10:00:00.000  INFO [,,] 12345 --- [nio-8081-exec-1] c.s.u.OrderController : 查询订单

# 开启后
2026-05-15 10:00:00.000  INFO [abc123,def456] 12345 --- [nio-8081-exec-1] c.s.u.OrderController : 查询订单

Feign 自动透传

Micrometer Tracing 自动在 Feign 调用中传递 TraceId，无需额外配置。调用链：

客户端 (traceId=abc)
  └── Gateway (traceId=abc, spanId=d1)
       ├── user-service (traceId=abc, spanId=e2)
       └── order-service (traceId=abc, spanId=f3)
            └── product-service (traceId=abc, spanId=g4)

自定义 Span

@Service
public class OrderService {

    private static final Tracer tracer = TracerHolder.getTracer();

    public Order createOrder(CreateOrderRequest req) {
        // 手动创建 Span
        ScopedSpan span = tracer.startScopedSpan("createOrder.deductStock");
        try {
            // 业务逻辑
            productFeignClient.deductStock(req.getProductId(), req.getQuantity());
        } catch (Exception e) {
            span.error(e);
            throw e;
        } finally {
            span.end();
        }
    }

    // 使用 @Observed 注解
    @Observed(name = "order.create",
              contextualName = "create-order",
              lowCardinalityKeyValues = {"service", "order"})
    public Order createOrderWithAnnotation(CreateOrderRequest req) {
        return doCreateOrder(req);
    }
}

Zipkin 界面使用

Zipkin 控制台：
1. 搜索：按服务名、Tags、时间范围查询 Trace
2. 看耗时：每个 Span 的耗时分布
3. 看依赖：服务间调用关系图
4. 查错误：红色标记的 Span（异常请求）

小结

• Micrometer Tracing（Spring Boot 3.x）替代了旧的 Sleuth。
• TraceId 贯穿所有服务，通过 W3C/B3 标准传播。
• Feign / RestTemplate / Gateway 自动透传 TraceId，零代码。
• 日志格式加上 [%X{traceId:-}] 即可关联日志与链路。
• Zipkin 可视化查看调用链、耗时、错误。
• 生产环境采样率推荐 0.1（10%），减少存储压力。

上一节：Sentinel + Feign 整合与规则持久化 下一节：项目架构与初始化

贡献者: 布欧-Lewyon