一、背景与核心概念
1.1 核心目标与工作流
在微服务架构中，分布式追踪是实现跨服务调用可观测性的基石。Spring Cloud Sleuth提供了对请求上下文的自动传播能力，确保在不同服务间传递的 traceId、spanId 等标识能被关联。通过这种机制，系统能够在一个全局链路中追踪请求的起点与各节点的执行情况。
通过 追踪上下文传播，同一请求在链路中的每个微服务都能记录自己的执行信息，便于快速定位瓶颈与错误。Sleuth 的设计目标是“零配置”的集成体验，同时支持与 Zipkin、Jaeger 等后端可视化工具对接，从而实现端到端的可观测性。
1.2 追踪数据结构与日志格式
Sleuth 会在每次入口处创建根 trace，随后为每个子操作创建 span，共同组成一个有向无环图（DAG）。日志中通常会看到 traceId 与 spanId 的搭配输出，从而实现跨服务的溯源。
为了企业级落地，标准日志模式（包括时间戳、日志级别、traceId、spanId、parentId 等）对诊断效率至关重要。我们在日志框架中启用 Sleuth 的日志前缀，确保系统日志与追踪日志可对齐，提升跨服务问题定位的效率。
# Sleuth 与 Zipkin 的基础配置示例
spring:sleuth:enabled: truesampler:probability: 0.5zipkin:base-url: http://localhost:9411enabled: true
二、快速落地：从依赖到首个追踪
2.1 快速接入与依赖管理
仅需要引入 spring-cloud-starter-sleuth 即可实现对调用链的自动追踪。自动传播功能无需手动编写上下文代码；开发者可以直接在业务逻辑层编写代码，Sleuth 会在后端自动完成 traceId、spanId 的注入与传播。
如果你还需要在可视化后端查看链路，可以引入 spring-cloud-starter-zipkin 或组合使用 Brave 相关组件，以便在 Zipkin 或 Jaeger 中呈现完整链路。
// Gradle 依赖示例
dependencies {implementation 'org.springframework.cloud:spring-cloud-starter-sleuth'implementation 'org.springframework.cloud:spring-cloud-starter-zipkin'
}
# 基本配置示例
spring:sleuth:enabled: truesampler:probability: 0.6zipkin:base-url: http://localhost:9411enabled: true
2.2 启动与验证
应用启动后，入口请求会携带一个全局 traceId，并在跨服务的调用链中持续传播。你可以在日志中看到格式化的追踪信息，例如 traceId 与 spanId 的组合，帮助定位问题。
为确保跨服务的追踪一致性，建议对入口和转发头部进行标准化设置，确保请求在网关、微服务之间传递时不丢失追踪信息。
// 示例：在自定义拦截器中输出 trace 信息（伪代码，实际场景以日志为主）
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import brave.Tracer;
import brave.Span;
import org.springframework.beans.factory.annotation.Autowired;public class TraceLogger {private static final Logger log = LoggerFactory.getLogger(TraceLogger.class);@Autowiredprivate Tracer tracer;public void logCurrentSpan() {Span span = tracer.currentSpan();if (span != null) {log.info("Current traceId={}, spanId={}", span.context().traceIdString(), span.context().spanIdString());}}
}
# 通过 OpenAPI/HTTP 请求头进行传播示例（伪代码）
# 请求头在网关进入后会被 Sleuth 自动注入
X-B3-TraceId:
X-B3-SpanId:
X-B3-ParentSpanId:
三、跨语言与跨框架的追踪传播
3.1 接入 Brave 与 OpenTelemetry 的思路
Spring Cloud Sleuth 基于 Brave 实现，核心是 Tracer 与 Span 的上下文传播。为了多语言服务的链路可视化，可以考虑搭配 OpenTelemetry 采集环境，将追踪端到端呈现给 Jaeger/Zipkin。
通过 OpenTelemetry SDK，你可以在 Node、Go、Python 等语言中创建等价的追踪信息，并通过相同的后端聚合分析，从而实现跨语言的统一观测。
3.2 主流后端的对接要点
在微服务架构中，跨进程调用需要确保请求头中包含正确的追踪信息头部：trace-id、span-id、以及 parent-id，Sleuth 提供了自动注入与读取能力，极大降低集成难度。
spring:sleuth:propagation:type: B3 # 也可选 W3C B3 等标准
四、可观测性与可视化工具对接
4.1 Zipkin 与 Jaeger 的对接要点
Zipkin 提供了直观的可视化链接视图，Sleuth 与 Zipkin 的结合可以实现“从代码到全链路”的快速定位。Base URL、采样概率、以及 服务名 等配置直接决定链路的覆盖范围。
Jaeger 作为另一大可观测后端，支持同样的上下文传播协议。对接时，确保后端端点、端口、以及采样策略一致，以避免链路数据丢失或不一致现象。
spring:sleuth:sampler:probability: 0.8zipkin:base-url: http://127.0.0.1:9411/discovery:enabled: true
五、性能调优与排错
5.1 采样控制与日志带宽
在高并发场景下，采样率的设定直接影响对后端存储和网络的压力。合理配置 spring.sleuth.sampler.probability，可以在可观测性和性能之间取得平衡。
日志大小与带宽也要关注，确保日志格式包含 traceId、spanId、以及关键业务字段，但不过量重复信息。
spring:sleuth:sampler:probability: 0.1
5.2 常见问题排错
常见问题包括追踪数据丢失、跨服务链路断裂、以及头部传递异常等。通过检查后端可视化工具的链路视图、以及应用日志中是否打印了正确的 traceId、spanId，可以快速定位问题所在。
