Spring Boot 3.x 开发中消息轨迹追踪的上下文传递问题详解

---

引言

在微服务架构中，分布式追踪（如通过 TraceId、SpanId 串联请求链路）是定位性能瓶颈和故障根源的重要手段。当业务涉及异步消息（如 RabbitMQ、Kafka）时，追踪上下文需要从生产者传递到消费者，才能形成完整的调用链。然而，在 Spring Boot 3.x 应用中，由于线程隔离、消息头未传递、MDC 丢失等原因，追踪上下文常常在消息传递过程中断裂，导致无法关联生产者和消费者的日志，给问题排查带来极大困难。本文将深入剖析消息轨迹追踪上下文传递的常见问题，并提供基于 Micrometer Tracing 的完整解决方案。

---

1. 问题表现：追踪上下文丢失的典型症状

• 现象 A：生产者发送消息前设置的 traceId，消费者收到消息后，日志中输出的 traceId 为空白或新的随机值，无法串联。
• 现象 B：使用 @RabbitListener 或 @KafkaListener 消费消息时，通过 MDC.get("traceId") 获取不到生产者传递的值。
• 现象 C：在异步线程池中处理消息，traceId 丢失，导致异步任务的日志无法关联到原始消息。
• 现象 D：使用 Spring Cloud Sleuth（Spring Boot 2.x）的项目升级到 Spring Boot 3.x 后，traceId 不再自动传递，因为 Sleuth 已被 Micrometer Tracing 替代，且配置方式发生变化。
• 现象 E：手动在消息头中添加 traceId，但消费者端因未正确解析头信息，导致无法恢复上下文。

---

2. 原因分析：上下文传递失效的根源

2.1 分布式追踪的基本原理

• TraceId：唯一标识一次完整请求链路。
• SpanId：标识链路中的一个操作单元。
• 在 HTTP 调用中，通过请求头（如 b3 头）传递上下文。在消息队列中，通常将上下文放入消息头（Message Headers）中传递。

2.2 Spring Boot 3.x 中的追踪演进

• Spring Boot 2.x：默认使用 Spring Cloud Sleuth + Brave，自动为 RabbitTemplate、KafkaTemplate 注入消息头，并在消费者端自动恢复 MDC。
• Spring Boot 3.x：弃用 Sleuth，全面转向 Micrometer Tracing + Brave 或 OpenTelemetry。需要显式配置才能实现消息头自动传递。

2.3 常见配置缺失导致的问题

• 未添加 micrometer-tracing-bridge-brave 或 micrometer-tracing-bridge-otel 依赖。
• 未配置 TracingObservationHandler 或未为消息中间件注册 MessageReceiver/MessageSender 自定义钩子。
• 使用 @Async 或其他线程池时，未将 MDC 上下文复制到子线程。

2.4 手动传递的陷阱

• 仅传递 traceId，而忽略 spanId 和采样标记，导致追踪系统无法正确构建父子关系。
• 消息头命名不规范（如使用 traceId 而非 b3-traceid），与追踪系统不兼容。

---

3. 解决方案：基于 Micrometer Tracing 的自动上下文传递

3.1 添加必要依赖（以 Brave 实现为例）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-integration-test</artifactId>
    <scope>test</scope>
</dependency>
<!-- 如果使用 RabbitMQ -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
<!-- 如果使用 Kafka -->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

3.2 配置 Micrometer Tracing 自动传播（无需额外代码）

Micrometer Tracing 为 RabbitMQ 和 Kafka 提供了开箱即用的 Observation 支持。只要添加了上述依赖，消息头会自动注入和提取。

验证：启动应用后，发送一条消息，观察消息头中是否包含：

• b3-traceid
• b3-spanid
• b3-sampled

示例：RabbitMQ 自动传播：

@Service
public class OrderProducer {
    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void sendOrder(Order order) {
        // 不需要手动设置任何头，Micrometer Tracing 会自动注入当前 trace 上下文
        rabbitTemplate.convertAndSend("order.exchange", "order.routing", order);
    }
}

@Component
public class OrderConsumer {
    @RabbitListener(queues = "order.queue")
    public void receive(Order order, Message message) {
        // 消息到达时，MDC 中已经自动包含了 traceId 和 spanId
        log.info("Received order: {}", order); // 日志中会显示正确的 traceId
        // 业务处理...
    }
}

3.3 处理异步线程池的上下文传递

如果消费者内部使用 @Async 或自定义线程池处理消息，需要手动复制 MDC 上下文，否则子线程会丢失 traceId。

方法一：使用 @Async 时配置 TaskDecorator

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {
    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        // 关键：复制 MDC 上下文
        executor.setTaskDecorator(new MdcTaskDecorator());
        executor.initialize();
        return executor;
    }

    static class MdcTaskDecorator implements TaskDecorator {
        @Override
        public Runnable decorate(Runnable runnable) {
            Map<String, String> contextMap = MDC.getCopyOfContextMap();
            return () -> {
                if (contextMap != null) {
                    MDC.setContextMap(contextMap);
                }
                try {
                    runnable.run();
                } finally {
                    MDC.clear();
                }
            };
        }
    }
}

方法二：使用 CompletableFuture 时传递上下文

CompletableFuture.supplyAsync(() -> {
    // 手动设置 MDC
    MDC.setContextMap(mdcContext);
    // 业务逻辑
}, executor);

3.4 手动发送消息时的上下文传递（如需自定义）

如果使用原生 RabbitTemplate 或 KafkaTemplate 的底层 API，可手动获取当前 TraceContext 并注入消息头。

@Autowired
private Tracer tracer; // Micrometer Tracing 的 Tracer

public void sendWithTrace(String exchange, String routingKey, Object message) {
    // 获取当前 trace 上下文
    Span currentSpan = tracer.currentSpan();
    if (currentSpan != null) {
        Map<String, String> headers = new HashMap<>();
        // 使用 B3 传播格式
        headers.put("b3-traceid", currentSpan.context().traceId());
        headers.put("b3-spanid", currentSpan.context().spanId());
        headers.put("b3-sampled", currentSpan.context().sampled() ? "1" : "0");
        // 将 headers 添加到消息中
        rabbitTemplate.convertAndSend(exchange, routingKey, message, msg -> {
            headers.forEach((k, v) -> msg.getMessageProperties().setHeader(k, v));
            return msg;
        });
    } else {
        rabbitTemplate.convertAndSend(exchange, routingKey, message);
    }
}

3.5 使用 OpenTelemetry 作为追踪桥接

若项目使用 OpenTelemetry，只需替换依赖：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>

并配置 OTLP 导出器，其余自动传播逻辑相同。

3.6 验证追踪上下文是否成功传递

• 在消费者日志中查看是否包含 traceId（需配置日志 pattern 包含 %X{traceId}）。
• 使用 Zipkin 或 Jaeger 查看 trace 详情，确认生产者 span 和消费者 span 在同一个 trace 中。

日志配置示例（logback-spring.xml）：

<Pattern>
    %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] traceId=%X{traceId} spanId=%X{spanId} %-5level %logger{36} - %msg%n
</Pattern>

---

4. 完整示例：Spring Boot 3.x + RabbitMQ + Micrometer Tracing

4.1 依赖（pom.xml）

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-amqp</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-brave</artifactId>
    </dependency>
    <dependency>
        <groupId>io.zipkin.reporter2</groupId>
        <artifactId>zipkin-reporter-brave</artifactId>
    </dependency>
</dependencies>

4.2 配置文件（application.yml）

spring:
  rabbitmq:
    host: localhost
    port: 5672
  zipkin:
    base-url: http://localhost:9411
  sleuth: # 虽然 Sleuth 已废弃，但部分属性仍可迁移
    sampler:
      probability: 1.0
management:
  tracing:
    sampling:
      probability: 1.0
    propagation:
      type: b3

4.3 生产者

@RestController
public class OrderController {
    @Autowired
    private RabbitTemplate rabbitTemplate;

    @PostMapping("/order")
    public String createOrder(@RequestBody Order order) {
        // 自动注入当前 trace 上下文到消息头
        rabbitTemplate.convertAndSend("order-exchange", "order-rk", order);
        return "OK";
    }
}

4.4 消费者

@Component
@Slf4j
public class OrderConsumer {

    @RabbitListener(queues = "order-queue")
    public void consume(Order order, Message message) {
        // 从消息头中获取 trace 信息（已由 Micrometer 自动提取并设置到 MDC）
        log.info("Received order: {}", order);
        // 模拟处理
        process(order);
    }

    private void process(Order order) {
        // 此处日志同样包含正确的 traceId
        log.info("Processing order {}", order.getId());
    }
}

4.5 启动应用，发送请求，查看 Zipkin

• 访问 POST /order，触发消息发送。
• 在 Zipkin 中搜索 trace，应该能看到一个包含 HTTP Server Span 和 RabbitMQ Producer/Consumer Span 的完整链路。

---

5. 最佳实践总结

• 优先使用 Micrometer Tracing：自动为 RabbitMQ、Kafka、HTTP 客户端注入和提取追踪上下文，无需手动编码。
• 统一日志格式：在日志 pattern 中包含 traceId 和 spanId，便于检索。
• 异步处理务必复制 MDC：任何异步线程（@Async、线程池、CompletableFuture）都需要手动复制 MDC 上下文，否则追踪断裂。
• 不要手动拼装 B3 头：除非有特殊格式要求，否则交给框架自动处理。
• 监控追踪数据采样率：生产环境可设置较低采样率（如 0.1），避免性能开销。
• 测试追踪链路：编写集成测试，验证消息传递后 traceId 的一致性。

---

6. 结语

消息轨迹追踪的上下文传递是分布式系统可观测性的关键一环。在 Spring Boot 3.x 中，通过 Micrometer Tracing 的自动传播机制，可以零代码实现 RabbitMQ 和 Kafka 的上下文传递。对于异步线程池等场景，只需额外复制 MDC 即可。希望本文能帮助开发者彻底解决消息队列中的追踪上下文丢失问题，构建清晰、完整的调用链。