Spring Cloud Sleuth 与当前 Spring Cloud 版本不兼容如何解决？

Question

**问题描述：** 在使用最新版本的 Spring Cloud 时，发现 Spring Cloud Sleuth 与当前版本不兼容，表现为自动追踪功能失效、日志中缺失 Trace ID 或启动时报类冲突异常。如何解决 Spring Cloud Sleuth 与当前 Spring Cloud 版本之间的兼容性问题？

Answer 1

解决 Spring Cloud Sleuth 与 Spring Cloud 最新版本的兼容性问题

1. 问题描述

在使用最新版本的 Spring Cloud（例如 2023.x 或更高）时，开发者发现 Spring Cloud Sleuth 的自动追踪功能失效，表现为：

• 日志中缺失 Trace ID 和 Span ID。
• HTTP 请求链路追踪无法自动关联。
• 应用启动时报出类冲突异常，如 NoClassDefFoundError 或 NoSuchMethodError。

2. 兼容性变化背景

Spring Cloud Sleuth 自 3.1.0 版本起，已逐步迁移至 Micrometer Tracing 项目，Spring Cloud Sleuth 的新版本不再包含完整的自动配置功能，而是作为 Micrometer 的集成适配层。

这意味着，若直接使用旧版 Sleuth 配置方式，可能导致与新版本 Spring Cloud 的兼容性问题。

3. 问题分析流程

      graph TD
      A[启动应用] --> B{是否引入 Sleuth 依赖？}
      B -- 否 --> C[追踪功能缺失]
      B -- 是 --> D{Sleuth 版本是否兼容 Spring Cloud？}
      D -- 否 --> E[类冲突异常]
      D -- 是 --> F{是否配置了日志格式？}
      F -- 否 --> G[日志中无 Trace ID]
      F -- 是 --> H[功能正常]
    

4. 解决方案步骤

1. 确认当前使用的 Spring Cloud 版本。
2. 访问 Spring Cloud 官网，查看该版本对应的 Sleuth 推荐版本。
3. 使用 Micrometer Tracing 替代部分 Sleuth 功能。
4. 更新依赖配置，确保版本对齐。
5. 检查日志格式配置，确保包含 Trace ID 和 Span ID。
6. 如使用 Zipkin 或其他追踪系统，需引入对应的 Micrometer 实现依赖。

5. 示例依赖配置（Maven）

Spring Cloud Version	Recommended Sleuth Version	Micrometer Tracing Version
2022.0.x (Kilburn)	3.1.x	1.0.x
2023.0.x (2023.0.x)	3.2.x	1.1.x

6. 依赖配置示例（Maven）

    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-sleuth</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-brave</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing</artifactId>
    </dependency>
  

7. 日志格式配置（logback-spring.xml）

    <pattern>
        %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg [trace=%X{traceId:-},span=%X{spanId:-}]%n
    </pattern>
  

此配置确保日志输出中包含 Trace ID 和 Span ID。

8. 其他注意事项

• 避免手动引入旧版 Brave 或 Zipkin 依赖，以免与 Micrometer 冲突。
• 如需自定义追踪逻辑，应使用 Micrometer Tracing 提供的 API。
• 使用 Spring Boot 3.x 时，注意是否启用 Jakarta EE 9+，Sleuth 是否兼容。