Spring Cloud Sleuth 全方位详解

以下是 Spring Cloud Sleuth 的全方位详解，涵盖其核心原理、功能特性、工作流程、配置项、集成方式、常见问题及未来演进方向。适合从入门到深入理解 Sleuth 的开发者、架构师使用。

---

🌟 Spring Cloud Sleuth 全方位详解

Sleuth 是 Spring Cloud 提供的分布式追踪解决方案，用于在微服务架构中自动为请求生成和传播追踪上下文（Trace ID、Span ID），帮助开发者定位性能瓶颈、排查跨服务调用问题。

---

一、Sleuth 是什么？

1.1 基本定义

• Spring Cloud Sleuth 是一个基于 Brave（Brave 是 Twitter 开源的 OpenTracing 实现）的分布式追踪库。
• 它不负责可视化展示，而是专注于 生成和传播追踪信息。
• 通常与 Zipkin、Jaeger 等后端系统配合使用 来实现调用链的收集与展示。

1.2 核心目标

• 自动为每个请求生成唯一的 Trace ID
• 为每个操作（如 HTTP 请求、方法调用）创建 Span
• 在服务间传递上下文（通过 HTTP Header 或消息中间件）
• 将追踪数据导出到外部系统（如 Zipkin）

---

二、核心概念解析

概念	说明
🔗 Trace（调用链）	代表一次完整的请求流程，贯穿多个服务。例如：用户 → 网关 → 订单服务 → 用户服务 → 支付服务
🧩 Span（跨度）	表示一个独立的工作单元，如一次 HTTP 调用、数据库查询。每个 Span 有唯一 Span ID，并属于某个 Trace
📦 Span Context	包含 Trace ID、Span ID 和其他 baggage（附加数据），用于跨进程传播
🔄 Context Propagation（上下文传播）	将 Span Context 通过 HTTP Headers（如 X-B3-TraceId）或消息队列传递给下游服务

示例日志格式：

[order-service,8a7bd13e12c54b8a,8a7bd13e12c54b8a,false]

• order-service: 当前服务名
• 8a7bd13e12c54b8a: Trace ID
• 8a7bd13e12c54b8a: Span ID
• false: 是否被采样上报（true 表示已导出）

---

三、工作原理详解

3.1 自动注入 Trace & Span

Sleuth 利用 Spring AOP 和拦截器机制，在以下场景自动创建 Span：

场景	如何处理
HTTP 请求进入	创建新 Span 或继续已有 Trace
Feign 调用	自动注入 B3 Headers
RestTemplate 调用	若启用拦截器，自动传播上下文
@Async 方法	支持线程间上下文传递（需注意）
消息生产/消费	Kafka/RabbitMQ 中自动注入 headers

3.2 上下文传播机制（B3 Headers）

Sleuth 使用 B3 Propagation 标准（来自 Zipkin）来传递追踪信息：

Header	说明
X-B3-TraceId	全局唯一标识一次请求链路
X-B3-SpanId	当前操作的 Span ID
X-B3-ParentSpanId	父 Span ID（可选）
X-B3-Sampled	是否采样（1=是，0=否）

示例：

GET /api/order HTTP/1.1
Host: localhost:8080
X-B3-TraceId: 8a7bd13e12c54b8a
X-B3-SpanId: 1a2b3c4d5e6f7g8h
X-B3-Sampled: 1

---

四、功能特性详解

4.1 自动追踪能力

组件	支持情况
Web MVC（Spring Web）	✅ 自动创建入口 Span
WebFlux（Reactive）	✅ 支持响应式编程模型
Feign Client	✅ 自动注入 B3 Headers
RestTemplate	✅ 需注册 TraceRestTemplateInterceptor
WebClient（Reactive）	✅ 支持
@Async 注解	✅ 支持线程池上下文传递
Kafka / RabbitMQ	✅ 生产者/消费者自动追踪
Gateway / Zuul	✅ 支持网关层追踪

4.2 日志集成（MDC）

Sleuth 自动将 traceId 和 spanId 写入 MDC（Mapped Diagnostic Context），便于日志系统检索。

配置 Logback 示例：

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{traceId}/%X{spanId}] %msg%n</pattern>
    </encoder>
</appender>

输出效果：

10:23:45.123 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - [8a7bd13e12c54b8a/8a7bd13e12c54b8a] Completed 200 OK

---

五、集成 Zipkin（核心组合）

5.1 添加依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zipkin</artifactId>
</dependency>

5.2 配置文件（application.yml）

spring:
  zipkin:
    base-url: http://localhost:9411
    sender:
      type: web  # 可选：web/kafka、rabbitmq
  sleuth:
    sampler:
      probability: 0.1  # 采样率 10%

5.3 数据上报方式

方式	说明
HTTP（web）	直接通过 REST API 发送到 Zipkin Server（最常用）
Kafka	将追踪数据发送到 Kafka Topic，Zipkin 消费
RabbitMQ	类似 Kafka，适用于 RabbitMQ 用户
gRPC	更高效，但需要 Zipkin 支持 gRPC 接收

---

六、高级配置与优化

6.1 采样策略（Sampler）

默认使用 ProbabilityBasedSampler，按概率采样。

自定义采样器：

@Bean
public Sampler customSampler() {
    return Sampler.create(0.5f); // 50% 采样率
}

或根据请求路径动态采样：

@Bean
public AlwaysSampler sampler() {
    return new AlwaysSampler(); // 全量采样（仅测试环境）
}

⚠️ 生产环境建议设置为 0.01 ~ 0.1，避免性能开销过大。

---

6.2 异步任务追踪

@Async
@NewSpan("async-task")
public void asyncProcess() {
    log.info("异步任务执行中...");
}

• @NewSpan 创建新的 Span
• Sleuth 会自动处理线程切换时的上下文传递（基于 TraceRunnable 和 TraceCallable）

---

6.3 手动创建 Span

有时需要手动控制追踪范围：

@Autowired
private Tracer tracer;

public void businessMethod() {
    Span customSpan = tracer.nextSpan().name("custom-operation").start();
    try (Tracer.SpanInScope ws = tracer.withSpanInScope(customSpan)) {
        // 业务逻辑
        log.info("执行自定义操作");
    } catch (Exception e) {
        Tags.ERROR.set(customSpan, true);
        throw e;
    } finally {
        customSpan.end();
    }
}

---

七、常见问题与解决方案

问题	原因	解决方案
❌ Trace ID 不连续	下游服务未正确接收 Headers	检查 Feign/RestTemplate 是否启用拦截器
❌ Zipkin 收不到数据	网络不通或配置错误	检查 base-url、防火墙、Docker 网络
❌ 日志无 traceId	MDC 未配置	检查日志 pattern 是否包含 %X{traceId}
❌ 异步任务丢失上下文	线程池未包装	使用 @Async + ThreadPoolTaskExecutor 并包装为 TraceableExecutorService
❌ 采样率太高影响性能	默认 1.0 导致全量上报	设置 sleuth.sampler.probability=0.05

---

八、Sleuth 的生命周期与未来趋势

⚠️ 重要提示：Sleuth 已被弃用（Spring Boot 3.x 起）

从 Spring Cloud 2022.0.0（即 Spring Boot 3.x）开始，Sleuth 被正式弃用，官方推荐迁移到 OpenTelemetry。

替代方案：OpenTelemetry（OTel）

对比项	Spring Cloud Sleuth	OpenTelemetry
标准化	基于 Brave（Zipkin）	CNCF 项目，行业标准
多语言支持	仅 Java	支持 Java/Go/Python/JS 等
指标 + 日志 + 追踪	❌ 仅追踪	✅ 三位一体（Observability）
社区活跃度	下降	高度活跃
Spring Boot 3.x 支持	❌ 不再支持	✅ 官方推荐

迁移建议：

1. 新项目直接使用 OpenTelemetry
2. 老项目逐步替换 Sleuth 为 OTel SDK
3. 使用 OTel Collector 统一接收并转发数据到 Zipkin/Jaeger/Grafana Tempo

📌 OpenTelemetry 快速上手：

<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
    <version>1.28.0</version>
</dependency>

---

九、最佳实践总结

✅ 推荐做法：

• 开发/测试环境：开启全量采样（probability=1.0）
• 生产环境：设置合理采样率（0.01 ~ 0.1）
• 结合 ELK/Loki 实现日志 + Trace ID 联合查询
• 使用 Zipkin 或 Grafana Tempo 进行可视化分析
• 所有微服务统一引入 Sleuth 依赖，确保链路完整
• 避免在敏感接口中记录 Span Baggage（避免泄露）

---

十、参考资料

类型	链接
官方文档	https://docs.spring.io/spring-cloud-sleuth/docs/current/reference/html/
GitHub 仓库	https://github.com/spring-cloud/spring-cloud-sleuth
Zipkin 官网	https://zipkin.io/
OpenTelemetry	https://opentelemetry.io/
Brave 库	https://github.com/openzipkin/brave

---

✅ 总结

维度	说明
定位	分布式追踪上下文生成与传播
优势	零代码侵入、自动集成 Spring 生态
局限	不支持可视化、已被 Spring Boot 3.x 弃用
适用场景	Spring Boot 2.x 微服务项目
未来方向	迁移到 OpenTelemetry