一、概述与目标
1.1 分布式追踪的价值
在微服务架构中，追踪跨服务调用的链路是实现高可观测性的关键。本文围绕 Spring Cloud Sleuth 与 Zipkin 整合配置详解与实战指南，介绍如何搭建、配置与调试追踪系统。
通过 Sleuth 的上下文传播和 Zipkin 的后端存储，开发者可以看到完整的调用链、延迟分布和根因分析信息。traceId、spanId 是核心标识，帮助追踪跨进程的请求。
1.2 Sleuth 与 Zipkin 的职责
Spring Cloud Sleuth 负责在应用内生成和传播追踪上下文，自动为请求打上 traceId、spanId，并在不同微服务间传递。Zipkin 则扮演后台存储与可视化的角色，汇聚这些 span 并提供 UI 展示。
通过 Zipkin 的 UI 与后端存储，可以清晰查看调用树、耗时分布和错误粒度信息，提升故障定位与性能调优效率。可观测性即由此实现。
1.3 实战指南的范围与边界
本文聚焦基于 Spring Cloud 版本的 Sleuth 与 Zipkin 集成场景，覆盖本地 Zipkin 服务、应用依赖配置、简单的自定义采样等。性能开销与部署成本需结合生产环境评估。
1.4 核心术语回顾
关键字段包括 traceId、spanId、parentId，以及 annotations 与 tags，共同描述调用链的时间线和上下文信息。
二、搭建本地 Zipkin 服务与测试环境
2.1 本地 Zipkin 服务部署
在本地快速启动 Zipkin 服务可借助 Docker，默认暴露端口 9411。安全性与持久化在开发阶段通常不作为重点，但生产环境需要额外考虑存储与高可用。
# 使用 Docker 启动 Zipkin 服务
docker run -d -p 9411:9411 openzipkin/zipkin2.2 验证 Zipkin 收集能力
通过一个简单的请求序列，触发 Sleuth 产生的追踪数据，并在 Zipkin UI 中查看。traceId 是跨请求追踪的关键。
# 触发一个简单请求（需要运行在已集成 Sleuth 的应用中）
curl http://localhost:8080/api/trace-test打开浏览器访问 http://localhost:9411/zipkin/，可以看到最近的 trace 和 spans。若未看到，请检查应用是否正确启动了 spring-cloud-starter-sleuth 与 zipkin。
三、在 Spring Cloud 应用中集成 Sleuth 与 Zipkin
3.1 添加依赖：Sleuth 与 Zipkin
在构建工具中引入 spring-cloud-starter-sleuth 与 spring-cloud-starter-zipkin，即可开启自动追踪与后端集成。下面给出 Maven 与 Gradle 两种写法。
<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-zipkin</artifactId>
</dependency>// Gradle (Groovy DSL)
dependencies {implementation 'org.springframework.cloud:spring-cloud-starter-sleuth'implementation 'org.springframework.cloud:spring-cloud-starter-zipkin'
}3.2 基础配置：传播与默认采样
Sleuth 会默认使用 B3 传播协议，将 traceId、spanId 等信息通过 HTTP 请求头传输。你可以通过简单的配置调整采样率和上游传播行为。
spring.zipkin.base-url: http://localhost:9411/
spring.zipkin.enabled: true
spring.sleuth.sampler.probability: 1.0 # 1.0 表示对所有请求都采样如果使用 application.properties，对应写法为：
spring.zipkin.base-url=http://localhost:9411/
spring.zipkin.enabled=true
spring.sleuth.sampler.probability=1.0通过 traceId 和 spanId，你可以在 Zipkin UI 中追踪到完整的调用链，诊断端到端的延迟。若不希望对全部请求采样，可以降低概率。动态采样 也可以结合外部配置中心实现。
3.3 自定义追踪点：@NewSpan 与自定义注解
在业务方法中添加 @NewSpan 注解，可以创建自定义的追踪子 Span，从而更细粒度地描述关键业务操作。以下示例演示一个简单的控制器方法。
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.cloud.sleuth.annotation.NewSpan;@RestController
public class TraceDemoController {@GetMapping("/order")@NewSpan("process-order")public String processOrder() {// 业务逻辑return "order-processed";}
}四、追踪数据在 Zipkin UI 的呈现与分析
4.1 查看与解释 Zipkin UI
Zipkin UI 提供了基于时间的调用链视图，trace 是跨越多个服务的请求链，span 代表各个阶段的子操作。通过 UI 可以直接查看 latency、annotations、以及异常信息。
# Zipkin UI 基本地址
http://localhost:9411/zipkin/常见字段包括：traceId、spanId、parentId、name、duration、timestamp。
4.2 常见场景与排查要点
如果某些请求未出现在 Zipkin 中，可能原因包括：Sleuth 未正确注入、Zipkin 服务未启动、采样比例过低等。对照以下要点排查：确认依赖版本兼容、检查 spring.zipkin.base-url 指向正确、验证日志输出中是否出现 TraceContext 信息。
五、进阶话题：跨语言追踪、OpenTelemetry 兼容性与扩展
5.1 跨语言调用的传播格式
Spring Cloud Sleuth 使用 BR Propagation，跨语言栈也需要对应的 traceId、spanId、parentId 编码。Zipkin 的后端可以接收多语言客户端的追踪数据，由此实现跨语言的一致追踪视图。
5.2 未来方向：OpenTelemetry 与兼容性
OpenTelemetry 提供了统一的观测模型，未来可以与 Sleuth/Zipkin 进行协同或替代，降低依赖多版本带来的维护成本。可在不改变现有 Zipkin 数据流的前提下，逐步引入 OpenTelemetry 的 API 与指标导出。
