我先讲一次真实的事故排查经历。有天线上突然收到一堆告警用户大面积反馈下单接口超时平均耗时从之前的200多毫秒飙到了4秒以上。我第一反应是打开订单服务的日志结果这个服务本身的耗时统计完全正常数据库没有慢查询Redis响应也一切正常。问题肯定在下游但下单服务后面挂了会员服务、库存服务、优惠券服务、支付服务……到底哪个环节把时间吞掉了日志里根本看不出来。后来我在系统里补上了服务调用链路追踪用Spring Cloud Sleuth配合Zipkin把整条调用链拉出来一看问题立刻锁定在优惠券服务的第三方接口上——对方服务偶发性变慢直接把整个下单链路拖垮。如果你也在Java后端做微服务大概率也会遇到类似的困境服务拆分之后一次业务请求往往要经过多个服务的协同处理任何一个环节出问题都会拖慢整条链路。这篇文章就围绕Spring Cloud Sleuth与Zipkin这套组合方案从核心原理、环境搭建、实操配置到生产环境踩坑完整过一遍服务调用链路追踪到底怎么落地、怎么排查问题适合正在做微服务改造、或者已经在微服务泥潭里挣扎的Java后端开发者参考。1. 微服务时代为什么传统日志突然不顶用了1.1 日志排障的困局服务一多日志就成了断案盲区单体应用时代排查问题很简单一个服务、一份日志请求进来、出去都在同一个进程里打点日志按时间排序就能还原整个处理过程。但微服务拆分之后一个请求会跨越多个服务实例每个服务自己记录的日志时间线是独立的排障时只能靠人工去各台机器上翻日志、凭经验拼凑调用顺序这个过程极其痛苦。更麻烦的是一次请求在服务A里记录了调用服务B的日志服务B也记录了收到请求的日志但是两条日志之间没有任何关联字段。如果没有TraceId贯穿始终你根本不知道这条日志对应的到底是哪次请求在高并发下多个请求交错写入日志文件人工根本没法区分。服务间排查基本靠猜效率极低。我在一次压测中就遇到过这种典型场景下单接口P99延迟从800ms飘到3.5秒但所有服务自己的平均耗时看着都正常因为大多数请求是快的只有极少数请求被下游的某个慢节点拖住。这种情况下聚合日志里看不到异常只有把单次请求的完整链路串起来才能看到那个被拖慢的环节。没有链路追踪这种偶发性能问题几乎无解。1.2 链路追踪要回答的三个核心问题链路追踪本质上是回答三个问题这次请求走了哪些服务每个服务花了多少时间失败或超时发生在哪个环节用生活中寄快递来类比一次完整的业务请求就像一件包裹从寄件人到收件人手里中间经过多个中转站。每个中转站都会给包裹贴上标签记录到达时间和离开时间。链路追踪做的事情就是在每个服务处理请求时生成这样的中转标签然后按照同一个包裹编号TraceId把所有标签串成一条完整的运输记录。这套方案在技术上并不神秘核心就是两个字段TraceId和SpanId。TraceId是一次请求全局唯一的编号用来标识这一件包裹SpanId是每一次服务调用的编号用来标识某一个中转站的处理过程。每个服务收到请求后把TraceId从上游传递下来处理完再传给下游这样所有服务的工作就能通过同一个TraceId关联起来。1.3 Spring Cloud Sleuth与Zipkin在这套体系里分别扮演什么角色在Spring Cloud生态里Sleuth和Zipkin是分工协作的关系Sleuth负责生成和传递链路数据Zipkin负责收集和展示链路数据。Sleuth是Spring Cloud家族里的链路追踪组件它会自动在HTTP请求、消息队列、Feign调用等场景里注入TraceId和SpanId不需要侵入业务代码。同时把埋点数据服务名、Span名、耗时、标签异步发送给Zipkin Server。Zipkin是Twitter开源的一套分布式链路追踪系统负责接收所有服务上报的链路数据存储在内存、MySQL或Elasticsearch里并提供Web UI供人查询链路详情、查看服务依赖关系图。Zipkin本身完全独立支持多语言客户端接入不局限于Java生态。简单说Sleuth是生成数据的探针Zipkin是展示数据的仪表盘。两者配合就构成了一条从埋点到展示的完整链路追踪闭环。2. 技术选型为什么这套组合在很多项目里仍是首选2.1 对比主流方案SleuthZipkin、SkyWalking、Pinpoint、Jaeger我在挑选链路追踪方案时把市面上主流的几套都过了一遍简单做了个对比对比维度Sleuth ZipkinSkyWalkingPinpointJaeger接入方式Java注解/自动装配侵入性低Java Agent探针零代码侵入Java Agent探针零代码侵入SDK/客户端集成数据采集应用主动上报Agent自动上报Agent自动上报应用主动上报界面丰富度基础链路查询、依赖图拓扑图、告警、监控完善调用链、实时监控较强链路查询、依赖分析存储依赖默认内存可接ES/MySQLES/H2/MySQLHBaseES/Cassandra学习成本低中中低更适合的场景中小规模Spring Cloud项目全链路监控、需要告警和拓扑的较大规模需要精细到方法级调用分析多语言异构系统大多数中小团队的第一诉求是先把调用链串起来看而不是复杂的告警和拓扑分析。SleuthZipkin在这一阶段是最快见效、最易维护的选择这也是它一直没有被淘汰的核心原因。2.2 选型要结合团队现状别为了先进而过度设计有一次和一个团队交流他们一上来就想上SkyWalking理由是这个看起来更高级有拓扑图还有告警。我问了他们三个问题服务数量有多少目前有没有统一的日志平台有没有人专门负责监控系统运维答案是服务十几个日志还停留在各自服务器上没有专职运维。这种情况下上SkyWalking光是Java Agent参数的调优、ES集群的维护、告警规则的设计就可能耗尽团队的精力更别说Agent探针对Java高版本、云原生环境的兼容性排查。相比之下SleuthZipkin部署简单、概念直观团队成员两天就能上手排查效率立刻提升。选型不是选最强大的而是选团队当前最能用起来的。2.3 什么时候应该升级方案当然链路追踪方案也有天花板。当服务规模扩大到几十上百个需要把追踪数据和业务告警、容量评估打通时单一Zipkin的展示能力就会显得单薄。这时候可以考虑三条演进路径把存储从内存换成Elasticsearch提升数据留存和查询能力。在Zipkin前面加上Kafka缓冲避免高并发下上报请求压垮Zipkin Server。在治理层面引入更完整的APM平台如SkyWalking借助拓扑和告警能力补充运维视角。需要注意的一点是链路追踪只是可观测性的一部分。成熟的运维体系还需要日志聚合和指标监控链路追踪负责回答一次请求发生了什么日志聚合负责回答某个服务内部发生了什么指标监控负责回答服务的整体健康度怎么样。三者协同才能形成完整的排障能力。3. 从零搭建依赖引入、Zipkin部署与核心配置3.1 版本选型Spring Boot与Spring Cloud版本对应关系版本选型是整个搭建过程中最容易踩坑的环节。Sleuth的版本跟随Spring Cloud版本走不同版本的Spring Cloud对应不同的Sleuth版本选错了启动直接报错。截至2024年中期Spring Cloud 2022.0.x及之后版本里Sleuth已经进入维护模式官方推荐使用Micrometer Tracing替代。但在大量存量项目中Sleuth仍然在稳定运行。如果你的项目是Spring Boot 2.x Spring Cloud 2021.0.x及更早版本可以直接使用Sleuth如果是Spring Boot 3.x Spring Cloud 2022.0.x的升级项目需要评估改造到Micrometer Tracing的迁移成本。我自己维护的一个老项目用的就是Spring Boot 2.7.x Spring Cloud 2021.0.8Sleuth版本为3.1.x运行非常稳定。技术选型不必盲目追新稳定运行的老方案在一个成熟项目里往往比激进升级更靠谱。3.2 Zipkin Server快速部署Docker是最省事的方式Zipkin Server的部署非常轻量。开发环境我用Docker一行命令搞定docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin:2.24.2默认数据存储在内存里重启即清空适合开发联调。生产环境建议把存储切换到Elasticsearch后面章节会专门讲生产化配置。部署完成后访问http://localhost:9411可以看到Zipkin的Web UI。如果本地确实不方便跑Docker也可以直接下载Zipkin的可执行Jar包运行java -jar zipkin-server-2.24.2-exec.jarZipkin依赖Java环境注意本地Java版本不要太高我自己遇到过Java 17下启动旧版Zipkin报模块错误的兼容性问题。3.3 服务端依赖引入与核心配置每个需要接入链路追踪的服务在pom.xml里引入Sleuth依赖dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-sleuth/artifactId /dependency如果需要通过HTTP方式上报给Zipkin再加上Zipkin客户端依赖dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-zipkin/artifactId /dependency然后在application.yml里做最小化配置spring: application: name: order-service zipkin: base-url: http://localhost:9411 sender: type: web sleuth: sampler: probability: 1.0spring.zipkin.base-url指向Zipkin Server地址spring.sleuth.sampler.probability表示采样率1.0代表100%采样。开发环境建议全量采样方便排查问题生产环境必须调低否则链路数据量会非常可观。3.4 业务代码零侵入Feign和RestTemplate的自动埋点机制Sleuth最让我满意的一点是对业务代码几乎零侵入。它通过Spring Cloud的自动装配机制在关键组件上自动添加埋点拦截器包括Feign调用自动在请求头中注入TraceId和SpanId并在调用结束后记录耗时。RestTemplate同样自动注入链路信息。Spring MVC的Controller入口自动生成新的Span。消息队列如Kafka、RabbitMQ消息生产者和消费者之间也能传递链路信息。这意味着只要项目原本就是用Feign或RestTemplate做服务间调用接入Sleuth后不需要改动任何业务类代码链路数据就能自动生成并上报。我第一次接入时只加了依赖和配置重启服务后去Zipkin页面刷新所有调用链都已经自动出现了这种体验确实很加分。4. TraceId的工作原理一次请求的全程通行证是怎么传递的4.1 TraceId与SpanId的生成规则和传递机制当一个请求第一次进入某个微服务的Controller时Sleuth会生成一个全局唯一的TraceId标识整个调用链同时生成一个SpanId标识当前这个服务处理环节。在请求通过Feign或RestTemplate调用下游服务时Sleuth自动把TraceId和SpanId放到HTTP请求头中传递下去。下游服务收到请求时从请求头里解析出上游传递的TraceId不再生成新的TraceId而是基于旧SpanId生成一个新的SpanId这样一次完整的调用链就通过TraceId串起来了。从数据结构上看链路是一条多叉树根Span是入口服务的处理过程每个子Span对应一次下游调用子Span下面还可以继续挂更深层的调用。Zipkin在展示时把这棵树还原成带时间轴的时序图每个Span的耗时一目了然。4.2 日志里如何把TraceId打出来logback配置实战链路追踪数据只有和日志关联起来才能发挥最大价值。在Zipkin页面上看到某个Span耗时过高你肯定要回到这个服务的日志里查看更多异常信息这时候如果没有TraceId做关联又回到了人工翻日志的老路。在logback.xml里加入traceId和spanId的输出是接入Sleuth后必须要做的一步pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-},%X{spanId:-}] %logger{36} - %msg%n/patternSleuth会把TraceId和SpanId写入MDCMapped Diagnostic Context日志框架可以直接通过%X占位符取出来。加上这两个字段后日志里每一行都带有链路标识排查问题时拿着Zipkin里的TraceId去日志系统里一搜所有相关日志全部出来效率提升非常明显。我通常还会把Zipkin页面的URL拼到日志输出里方便直接跳转。这一步看起来简单但对排查效率的提升是实实在在的。4.3 异步线程和消息队列场景下的链路信息传递一个容易被忽视的坑在Spring Async异步线程、以及自己手动创建线程池的场景下链路信息不会自动传递。因为链路信息存在ThreadLocal里线程切换后新线程拿不到父线程的MDC上下文TraceId就断了。Sleuth官方提供了解决方案在Spring Boot 2.x下可以通过配置自动增强线程池spring: sleuth: async: enabled: true对于使用Async注解的方法Sleuth会自动包装任务把父线程的TracerContext传递到子线程。配置之后不需要额外代码。但如果项目里有手动创建线程池的地方比如ExecutorService.newFixedThreadPool()Sleuth的自动增强就覆盖不到了。这时的通用做法是使用LazyTraceExecutor包装Bean public Executor traceExecutor(Tracing tracing) { return new LazyTraceExecutor(tracing, Executors.newFixedThreadPool(5)); }消息队列的场景类似生产者发送消息时Sleuth会把链路信息写入消息头消费者消费时Sleuth自动从消息头中解析并恢复链路信息。消费者处理逻辑里的耗时也会被计入同一个Span完整覆盖异步调用的链路追踪。5. 亲手跑通的Demo一次完整调用链的生成与排查演示5.1 Demo环境准备三个服务的拓扑结构为了把原理落成实操我搭了一个最小可复现的Demo包含三个Spring Boot服务刚好覆盖一次典型的业务链路gateway-service入口网关负责接收外部请求转发到order-service。order-service订单服务接收下单请求后调用inventory-service扣减库存。inventory-service库存服务模拟耗时操作比如数据库读写。服务间调用全部通过OpenFeign完成。三个服务都接入了Sleuth和Zipkin在本地同时启动后访问一次下单接口POST /api/orders整条链路的Trace就生成了。5.2 链路数据怎么看Zipkin UI实际操作步骤打开http://localhost:9411点击查询按钮输入服务名order-service和时间范围可以看所有经过order-service的链路。点击任意一条链路能看到完整的时序图gateway-service的Span在最上层耗时是整个链路的总耗时。order-service的Span作为子Span展示订单落地时间。inventory-service的Span展示扣减库存的时间。每个Span都能展开看详细信息比如HTTP方法、URL、状态码耗时数据会精确到微秒。哪个调用慢一眼就能锁定。我在Demo里故意在inventory-service的接口实现里加了一个Thread.sleep()模拟下游慢接口。Zipkin时序图上inventory-service的Span耗时明显拉长order-service的Span也随之变长总耗时和业务现象完全吻合。这种直观对应关系正是链路追踪在排障中的核心价值。5.3 依赖图一键看清服务间调用关系Zipkin还有一个非常好用的功能依赖图。在导航栏点击Dependencies可以看到服务间的调用关系拓扑清楚地展示某个服务被哪些服务调用、某个服务调用了哪些下游。这个功能在梳理存量系统时特别好用。之前接手一个祖传项目光靠看代码根本理不清服务调用关系用Zipkin的依赖图跑一天数据整个系统的调用拓扑就全出来了。相比人工翻代码效率高了一个量级。6. 生产环境踩坑实录那些文档里没写的事6.1 采样率设置不当导致的数据时有时无生产环境把采样率设为1.0全量采样是我见过最普遍的错误配置。全量采样带来的问题很直接每个请求都会生成链路数据并上报在高并发场景下Zipkin Server很快就会被打爆也会消耗大量存储空间。但采样率调太低也有问题。我遇到过把一个核心服务采样率调成0.110%结果排查一个偶发超时问题的时候点击十次请求只有一次能看到链路数据根本没法有效采样。生产环境的采样率设置需要结合业务流量来评估。以单台服务每秒1000个请求为例1.0全量采样每秒生成1000条链路Zipkin压力大但排查问题最方便。0.1采样率每秒生成100条链路偶发问题捕获概率降低。0.01采样率每秒生成10条链路量大时用这个但几乎无法用于偶发问题排查。我的建议是核心交易链路用0.5~1.0的采样率非核心服务用0.1~0.3再通过Zipkin的存储后端承载能力做上限评估。同时保留一个故障时动态调采样率的思路通过配置中心在排查问题时临时把采样率调高问题解决后再恢复。6.2 时间戳对不上服务器时钟漂移造成的灵异现象有一次在Zipkin页面看到同一个链路里下游服务的Span开始时间比上游服务还要早几十毫秒。第一反应是Sleuth的埋点逻辑出问题了查了半天代码结果问题出在服务器时钟不一致上。Zipkin的时序图完全基于各服务上报的时间戳如果服务间的系统时钟有偏差展示出来的链路顺序就是错的甚至会出现下游先执行的假象。解决方法是统一整个基础环境的NTP时间同步尤其是容器化部署的环境中宿主机和容器、不同宿主机之间的时钟偏差都可能造成这个问题。我排查过一次这类问题两个服务跑在不同机房的虚机上时钟差了约200毫秒导致链路时序图看起来下游服务先于上游执行当时查了很久才定位到是时钟问题。链路追踪依赖时间线时钟同步是基础中的基础建议在上线链路追踪之前先统一NTP。6.3 异步场景的链路断裂看似没问题实则Span层层丢失前面提过异步线程和消息队列的链路传递问题。在实际生产项目里我见过最隐蔽的情况是调用链从一个服务传到下一个服务中间经过一个异步线程池处理后后面的链路全部断开Zipkin页面上只有前半段链路。排查思路是先确认链路断裂点拿到TraceId后在日志里搜看看断裂位置的后半段日志里还有没有TraceId。如果后半段日志里完全没有TraceId说明线程切换时TracerContext丢了如果有TraceId但Zipkin里没有Span则可能是上报配置的问题。解决方式分别对待同步转异步的调用使用LazyTraceExecutor包装线程池消息队列场景检查消息头是否被业务代码覆盖。特别注意在把消息发送给第三方时如果手动修改了消息头原来的链路信息可能被覆盖掉。6.4 服务地址显示成实例名排查时的信息不全问题默认配置下Zipkin依赖图里的节点显示的是服务实例名而不是IP地址。在服务实例频繁重启、或者一个服务部署了多个实例时仅凭实例名很难定位到具体是哪台机器出了问题。我建议在接入链路追踪时把服务实例的IP和端口放到Span的Tag里这样排查时能直接定位到具体实例。放开Zipkin的上报限制后客户端上报时可以带自定义Tag比如spring: sleuth: tag: instance: ip-enabled: true不同版本配置略有差异核心思路是在Span的Tag里记录实例IP、部署环境、版本号等信息。这些Tag会随Span一起上报到Zipkin排障时可以按Tag过滤精确定位到问题实例。7. 数据上报了但Zipkin查不到一次完整的排查链路7.1 现象描述与初步排查清单接入Sleuth和Zipkin后最常遇到的问题就是服务日志里已经出现了TraceId但Zipkin页面上查不到任何数据。我整理一下完整排查思路供读者参考。第一步先自查上报配置spring.zipkin.base-url有没有配错地址或端口。服务是否真的引入了spring-cloud-starter-zipkin依赖只引入Sleuth是不会自动上报的。采样率spring.sleuth.sampler.probability是否不为0。把这三个基础项确认完后如果还没解决按下面两条路径继续排查。7.2 网络链路和版本兼容性排查最容易忽视的两个原因第二步排查网络链路。Zipkin上报走HTTP服务所在网络环境能否访问到Zipkin Server的9411端口是关键。尤其在新起的容器环境或者存在防火墙的机房服务调用没问题但上报数据被防火墙拦截的情况很常见。从服务所在机器上直接测试curl -X POST http://zipkin-server:9411/api/v2/spans \ -H Content-Type: application/json \ -d []返回正常即网络通。第三步排查版本兼容性。Spring Boot 2.x和Spring Cloud 2021.0.x的组合要用Sleuth 3.1.xSpring Cloud 2020.0.x对应Sleuth 3.0.x版本不匹配时Sleuth的自动装配可能静默失效日志不会报错但数据就是不上报。这类问题最坑因为日志输出一片正常根本不会往版本方向想。排查时直接打开Maven依赖树确认实际加载的Sleuth和Zipkin客户端版本。我在一次项目中就踩过这个坑项目用的是Spring Boot 2.4.5和Spring Cloud 2020.0.3依赖里强制指定了Sleuth 3.1.3结果部分服务的链路数据死活不上报。后来把Sleuth版本统一降到3.0.x问题瞬间解决。7.3 Zipkin Server端排查从日志和监控找线索第四步排查Zipkin Server本身。进入Zipkin Server容器或查看启动日志确认没有异常报错。在Zipkin Server的日志里如果看到大量连接拒绝或者OOM信息说明服务端已经扛不住。数据量大的情况下Zipkin Server的默认内存存储很容易成为瓶颈存储满了之后新数据写不进去API查询结果自然为空。这时候最简单的验证方式是重启Zipkin Server看是否恢复或者直接切换到Elasticsearch存储再观察。排查链路完整走下来90%以上的数据不上报问题集中在版本不匹配和采样率配置上网络和存储是次高频原因。这套排查思路基本能覆盖大多数情况。8. 从能看链路到能治理系统链路追踪的生产化演进8.1 存储升级从内存到Elasticsearch开发环境的Zipkin默认使用内存存储一旦重启历史链路数据全部丢失。生产环境必须把存储切换到ElasticsearchZipkin提供多种存储后端其中ES是最常用的。Docker启动Zipkin时通过环境变量配置ES存储docker run -d -p 9411:9411 \ -e STORAGE_TYPEelasticsearch \ -e ES_HOSTShttp://elasticsearch:9200 \ openzipkin/zipkin:2.24.2切到ES存储后链路数据可以长期保留支持按时间范围查询还能配合Kibana做进阶分析。数据量大时还要考虑索引生命周期管理定期清理历史数据避免ES存储膨胀。8.2 用Kafka做缓冲高并发下的上报链路容灾设计当服务规模和调用量上来之后每个服务的链路数据直接通过HTTP上报给Zipkin Server在高并发下可能造成Zipkin Server的请求积压甚至拖垮服务。这时候就需要引入Kafka作为缓冲层。架构变成服务实例 - Kafka - Zipkin Server。服务端配置改为spring: zipkin: sender: type: kafka kafka: bootstrap-servers: localhost:9092Sleuth会把链路数据发送到Kafka的指定TopicZipkin Server从Kafka消费数据并写入存储。这样做的好处是服务上报数据是异步的即使Zipkin Server短暂不可用消息也不会丢失。高并发场景下这条架构是链路追踪生产化的标配。8.3 链路和日志、告警联动可观测性的闭环把链路追踪用好不能只看链路数据本身而是要打通日志、指标和告警三个维度。链路追踪给出TraceId后日志平台能根据TraceId定位到全链路日志指标监控能告诉你在某段时间内某个服务的错误率、RT变化趋势告警系统能在指标异常时主动通知。我实际在做的事情是把日志平台和Zipkin打通日志平台支持按TraceId搜索同时Zipkin页面能一键跳转到日志平台的TraceId查询。这样在Zipkin里看到慢Span点一个链接就能把所有相关日志拉出来排障时间从小时级降到分钟级。再进一步可以把链路追踪数据与告警规则联动。比如某个服务的调用成功率下降时自动拉取相关链路的TraceId列表写入告警详情。这样运维人员收到告警时不仅知道有问题还能直接看到具体是哪条调用链出的问题处理效率大幅提升。我在实际落地这套体系的过程中最大的体会是链路追踪的价值不在于装上了而在于用得好。如果只是搭好Zipkin看个链路图那最多算入门真正把它融入日常排障、容量评估、故障复盘流程才能发挥出可观测性的全部价值。建议每个做微服务的团队都先把SleuthZipkin这套基础组合跑起来然后在实践中逐步演进。链路断了、数据查不到、时序错乱这些坑我都会在后续文章里拆开细讲。