在单体应用时代，排查问题往往只需要顺着一份日志文件往下翻，找到报错的位置基本就能定位原因。可一旦系统拆分成十几个甚至几十个微服务，一个用户请求可能要跨越网关、订单服务、库存服务、支付服务，最后还要发一条消息到MQ，任何一环出现延迟或异常，都会让整体接口变慢甚至失败，而传统的日志排查方式几乎无从下手。Spring Cloud Sleuth就是Spring官方推出的分布式链路追踪解决方案，它能够在请求进入系统的那一刻生成一个全局唯一的Trace ID，并沿着调用链路自动传递到每一个下游服务，让你在日志中一眼看清整个请求的完整路径。本文将从核心概念、工作原理、与Zipkin的整合实践以及常见问题几个方面，把Sleuth的入门知识讲透。
一、Spring Cloud Sleuth的核心概念：Trace与Span
理解Sleuth的第一步是弄懂它的数据模型。Sleuth借鉴了Google Dapper论文的设计思想，采用Trace和Span两个层级来描述调用关系。Trace代表一次完整的请求链路，从请求进入系统的入口开始，到最终响应返回结束，整个过程中不管跨越了多少个服务，都属于同一个Trace。Span则代表链路中的一个独立工作单元，比如订单服务处理请求是一个Span，订单服务调用库存服务的HTTP请求是另一个Span，Span之间通过父子关系串联起来，最终形成一棵调用树。
每一个Span都带有四个关键标识：Trace ID、Span ID、父Span ID以及导出标识。Sleuth会自动把这些信息注入到日志上下文中，接入后日志格式会变成类似下面的样子：
2024-01-15 10:23:45.123 INFO [order-service,4bf92f3577b34da6a6ce9e6dcb2ed157,4bf92f3577b34da6a6ce9e6dcb2ed157,false] 30325 --- [nio-8080-exec-1] c.e.o.OrderController : 订单创建成功
日志开头方括号里的四段内容分别是应用名、Trace ID、Span ID和是否导出到Zipkin。有了Trace ID，运维人员在海量日志中只需一条grep命令，就能把一次请求在所有服务中产生的日志全部筛选出来，这种能力在跨服务排查时价值巨大。值得一提的是，这些ID是在进程内通过MDC（Mapped Diagnostic Context）机制注入的，因此对业务代码完全透明，开发者不需要手动传递任何参数。
二、Sleuth的工作原理与快速接入
Sleuth的接入方式非常简单，这是它相比自研追踪方案最大的优势。在Spring Boot项目中只需引入依赖即可，以Maven为例：
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
引入依赖后不做任何配置，Sleuth就会自动完成埋点。它的工作原理可以概括为三个层面：第一，通过Servlet Filter在HTTP请求进入时检查请求头中是否携带Trace信息，如果没有则生成新的Trace ID和Span ID；第二，对常见的通信组件进行增强，包括RestTemplate、OpenFeign、WebClient、RocketMQ和Kafka等，在发起调用时把当前Trace上下文写入请求头或消息头，实现跨进程传递；第三，通过装饰日志框架的MDC，把Trace ID注入到每一条日志里。这三个层面配合起来，就实现了所谓的透明埋点。
如果你想自定义日志格式来突出显示Trace ID，可以在日志配置中显式引用。下面是logback的一个参考配置片段：
<property name="LOG_PATTERN"
value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId:-},%X{spanId:-}] %logger{36} - %msg%n"/>
这里的%X{traceId}就是从MDC中读取Trace ID，中间的:-表示没有值时显示为空，避免在非Web线程中出现null字样。另外需要注意，Sleuth默认对异步线程池不做自动传递，如果业务中使用了自定义线程池，需要配合LazyTraceExecutor包装，否则子线程的日志会丢失Trace ID，这是很多人接入后遇到的第一个坑。
三、与Zipkin整合实现可视化追踪
Sleuth本身只负责生成和传递链路数据，如果想看到直观的调用链路图，就需要把数据上报到Zipkin。整合方式同样很简单，先添加依赖：
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-sleuth-zipkin</artifactId>
</dependency>
然后在配置文件中指定Zipkin Server的地址和采样率：
spring:
zipkin:
base-url: http://127.0.0.1:9411
sleuth:
sampler:
probability: 1.0 # 采样率，1.0表示全部采集，生产环境建议0.1
采样率是一个需要认真权衡的参数。全量采集虽然信息完整，但上报数据本身也有网络和存储开销，在高并发系统里可能占到请求延迟的百分之一以上；采样率设得太低又可能恰好漏掉那次出问题的请求。常见的实践是开发测试环境设为1.0，生产环境根据流量大小设为0.1甚至更低，或者结合条件采样策略，只对异常请求和慢请求做全量上报。数据上报到Zipkin后，在Zipkin的Web界面中输入Trace ID，就能看到瀑布图形式的调用链，每个Span的起止时间、耗时占比一目了然，定位慢在哪个服务变成了一件几分钟就能完成的事。
四、常见问题解答汇总
问题一：为什么日志里的Trace ID在新服务里变了？ 这种情况通常是因为下游服务没有接入Sleuth，或者请求是通过Sleuth没有增强的组件发出的，比如直接用原生HttpClient发请求。解决办法是统一使用RestTemplate或OpenFeign，或者手动把Trace ID塞进请求头。
问题二：为什么Zipkin页面上查不到数据？ 先检查Zipkin的地址配置是否正确，再确认依赖里加的是spring-cloud-sleuth-zipkin而不是只有sleuth基础包。如果用的是Zipkin 2.8之后的服务端版本，还要确认客户端用的是HTTP方式上报而不是旧的MQ方式，两者协议不兼容。
问题三：Sleuth和Micrometer Tracing是什么关系？ 从Spring Boot 3.0开始，Sleuth已经被移出了Spring Cloud家族，其功能由Micrometer Tracing接替，核心概念完全一致，只是包名和自动配置类发生了变化。新项目如果基于Spring Boot 3.x，建议直接使用Micrometer Tracing加Zipkin的方案；老项目继续用Sleuth也完全没问题，两者在思路上是相通的，学会其中一个，迁移到另一个的成本很低。
总的来说，Sleuth用极低的接入成本解决了微服务链路追踪这个高频痛点，理解了Trace和Span的数据模型、透明埋点的传递机制以及采样策略的取舍，你就能在排查线上问题时真正体会到它的价值。配合Zipkin的可视化界面，从发现问题到定位瓶颈的整个过程可以缩短到几分钟，这正是链路追踪被称为微服务治理基础设施的原因。
Spring Cloud Sleuth分布式链路追踪微服务监控修改时间：2026-09-10 19:18:41