SpringBoot 3.0.2集成Micrometer Tracing：日志自动关联Span/Trace ID失败

云上老周

2026-8-1

排查与解决步骤

1. 补全Brave与Log4j2的桥接依赖

Micrometer Tracing通过Brave桥接时，必须依赖brave-log4j2才能将Trace/Span ID注入Log4j2的MDC上下文，缺失该依赖会导致日志模板无法获取到对应ID值。

检查你的依赖配置，确保包含以下内容：

Maven

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-log4j2</artifactId>
</dependency>

Gradle

implementation 'io.zipkin.brave:brave-log4j2'

2. 验证Log4j2模板的MDC键正确性

Brave默认将Trace/Span ID存入MDC的X-B3-TraceId、X-B3-SpanId键，但也支持配置为无前缀的traceId、spanId。可以先在日志模板中同时添加两种键测试：

[%X{X-B3-TraceId}] [%X{X-B3-SpanId}] [%X{traceId}] [%X{spanId}] %msg%n

如果无前缀键能输出值，说明你的配置修改了MDC键格式，需调整模板匹配正确的键名。

3. 确保ESAPI日志传递MDC上下文

ESAPI若未正确绑定Log4j2，会丢失MDC中的Trace/Span信息。修改ESAPI.properties配置文件，指定Log4j2作为日志提供者：

ESAPI.Logger=org.owasp.esapi.reference.Log4J2LogFactory

同时确认ESAPI日志调用在当前请求上下文线程中执行，避免异步场景下的MDC丢失。

4. 处理异步线程的上下文传递

如果日志在异步任务中打印，需确保Trace上下文能传递到异步线程。Spring Boot 3.x可通过配置TaskExecutor实现：

@Bean
public TaskExecutor taskExecutor(Tracer tracer) {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setTaskDecorator(new TraceTaskDecorator(tracer));
    // 按需配置线程池参数
    executor.initialize();
    return executor;
}

该配置会自动将父线程的Trace上下文传递给异步任务。