Spring Boot 3迁移后Micrometer Tracing无法解析Traceparent头问题

问题背景 #

迁移到 Spring Boot 3 并改用 micrometer-tracing-bridge-otel 后，系统无法解析请求头中的 Traceparent 父链路 ID，生成全为0的默认父ID，导致 Zipkin 中应用间链路断开。测试命令：

curl --location --request GET 'http://localhost:8080/test' --header 'Traceparent: 00-63cf0173620c57b0aed605ee94255089-1444ca74c3d2133a-01'

解决步骤 #

1. 完善依赖配置

确保依赖完整且版本兼容，补充 Otel Spring 自动配置依赖，让框架自动处理 HTTP 请求的链路上下文提取：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.2</version>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
        <version>1.0.3</version> <!-- 与 Spring Boot 3.0.2 兼容版本 -->
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-spring-boot-starter</artifactId>
        <version>1.28.0</version> <!-- 版本需与上述依赖匹配 -->
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-zipkin</artifactId>
    </dependency>
    <dependency>
        <groupId>io.zipkin.reporter2</groupId>
        <artifactId>zipkin-sender-urlconnection</artifactId>
    </dependency>
</dependencies>

2. 配置 W3C 链路上下文传播器

在 application.properties 中明确启用 W3C Trace Context 传播器，确保 Traceparent 头被正确解析：

# 指定使用 W3C Trace Context 格式解析链路头
otel.propagators=tracecontext

3. 修正 Span 创建方式

避免手动创建根 Span，需基于请求上下文创建子 Span，或使用注解简化操作：

方式一：手动基于父上下文创建子 Span

@RestController
public class Test {

    @Autowired
    private Tracer tracer;

    @GetMapping(path="/test")
    public ResponseEntity<?> handleTest() {
        // 获取请求自动解析的父 Span 上下文
        Span parentSpan = tracer.currentSpan();
        if (parentSpan != null) {
            // 基于父上下文创建子 Span
            try (Span span = tracer.spanBuilder("test span")
                    .setParent(parentSpan.context())
                    .startSpan()) {
                // 业务逻辑处理
                return ResponseEntity.ok();
            }
        } else {
            // 无父上下文时创建根 Span
            try (Span span = tracer.spanBuilder("test span").startSpan()) {
                return ResponseEntity.ok();
            }
        }
    }
}

方式二：使用注解自动创建子 Span

@RestController
public class Test {

    @GetMapping(path="/test")
    @NewSpan(name = "test span")
    public ResponseEntity<?> handleTest() {
        return ResponseEntity.ok();
    }
}

4. 验证效果

重新启动应用后，执行测试curl命令，查看 Zipkin 控制台，此时当前 Span 的父 ID 应显示为 1444ca74c3d2133a，链路关联恢复正常。

核心原因 #

• 默认配置未启用 W3C Trace Context 传播器，导致 Traceparent 头无法被解析
• 手动调用 tracer.startScopedSpan 会直接创建根 Span，未继承请求中的链路上下文
• 缺少 Otel Spring 自动配置依赖，框架无法自动提取请求头中的链路信息

内容的提问来源于stack exchange，提问作者user3908406