Spring Cloud Gateway集成Micrometer Tracing始终输出相同TraceId问题

一、依赖冲突排查 #

• 检查pom.xml中是否存在旧版Spring Cloud Sleuth依赖，两者共存会导致上下文传播逻辑冲突，必须排除。示例：

  <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-gateway</artifactId>
      <exclusions>
          <exclusion>
              <groupId>org.springframework.cloud</groupId>
              <artifactId>spring-cloud-starter-sleuth</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

• 确认Micrometer Tracing与Brave桥接的依赖版本匹配，建议使用Spring Boot/Spring Cloud官方推荐的版本组合（如Spring Boot 3.x对应Micrometer Tracing 1.1.x+）。

二、上下文传播初始化检查 #

• 确保Hooks.enableAutomaticContextPropagation()在应用启动最早期调用，比如启动类main方法的第一行，不能晚于Bean初始化：

  public class GatewayApplication {
      public static void main(String[] args) {
          Hooks.enableAutomaticContextPropagation();
          SpringApplication.run(GatewayApplication.class, args);
      }
  }
  

• 检查自定义Executor或线程池，需手动配置上下文传播，否则异步线程会复用旧TraceContext：

  @Bean
  public Executor traceAwareExecutor() {
      return ContextPropagatingExecutorService.wrap(Executors.newFixedThreadPool(10), ContextSnapshot::captureAll);
  }
  

三、Gateway过滤器配置验证 #

• 排查自定义全局过滤器的优先级，若优先级高于TraceWebFilter（Brave的Web过滤器），会导致TraceContext无法正确初始化。可通过日志打印过滤器执行顺序，确认TraceWebFilter在请求处理早期执行。
• 确认未禁用Gateway或Tracing的自动配置，启动类上不能排除GatewayAutoConfiguration或MicrometerTracingAutoConfiguration。

四、配置参数校验 #

• 检查application.yml/application.properties中的追踪配置，确保参数正确：

  management:
    tracing:
      sampling:
        probability: 1.0 # 采样率设为100%，避免采样逻辑异常
      propagation:
        type: B3 # 与下游服务保持一致，默认B3，配置错误会导致上下文无法重置
  

• 若自定义了TraceContext或Tracer Bean，需确保是请求作用域而非单例，单例会导致所有请求复用同一个TraceId。

五、日志输出验证 #

• 检查日志格式是否正确引用Brave默认的MDC键traceId，比如logback配置：

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

• 若日志TraceId相同但Tracer.currentSpan()在请求中是新实例，说明MDC未正确重置，需检查过滤器是否在请求结束后清理了MDC上下文。

六、极端场景排查 #

• 检查是否存在请求缓存或复用情况，比如Gateway启用了请求缓存，或使用单例请求处理Bean导致上下文未隔离。
• 用不同客户端（Postman、curl）发起请求，排除客户端重复发送X-B3-TraceId头导致的TraceId复用问题。

内容的提问来源于stack exchange，提问作者疯子Max