微服务可观测性实战：分布式链路追踪从入门到精通

前言

微服务架构已经成了现代后端系统的主流选择。把一个单体应用拆成几十甚至上百个服务之后，每个服务的开发和部署确实灵活了，但排查问题变得异常困难------一个请求从网关进入，经过订单服务、库存服务、支付服务、积分服务，调用链条动辄七八层。某个环节慢了，到底是哪个服务的问题？日志散落在几十台机器上，要翻多久才能找到根因？

这就是分布式链路追踪要解决的问题。它本质上是在微服务架构中给每个请求生成一个唯一的 Trace ID，让这个 ID 像快递单号一样贯穿整个调用链，把所有服务产生的日志、耗时数据串联起来。链路追踪与指标（Metrics）、日志（Logging）共同构成了可观测性的三大支柱，三者互为补充，指标告诉你"系统的宏观健康状况如何"，日志让你"深入查看某次请求的详细记录"，而链路追踪则帮你"精准定位请求经过的完整路径和每个环节的耗时瓶颈"。

本文将带你深入理解分布式链路追踪的核心原理，对比不同技术方案的演进路线，并通过完整代码示例实操落地，最后分享生产环境的最佳实践。

一、认识分布式链路追踪

1.1 核心概念

链路追踪的核心模型源于 Google 的 Dapper 论文，主要包括三个核心概念：

概念	说明	示例
Trace ID	一次完整请求的唯一标识，贯穿所有服务	abc123xyz
Span ID	链路中的一个基本操作单元，每个调用环节都有独立的 Span ID	span-001
Parent Span ID	标识上层调用者，用于构建调用树	span-000

可以把一次分布式请求理解为一棵调用树：一个 Trace 由多个 Span 构成，Span 之间通过 Parent-Child 关系形成层级结构。比如用户下单这个 Trace，可能包含：网关接收请求（Span A）→ 订单服务处理（Span B，Parent为A）→ 库存服务扣减（Span C，Parent为B）→ 支付服务调用（Span D，Parent为B）。通过这种结构，可以在可视化界面上清晰地看到请求的完整路径。

1.2 核心原理：上下文传播

链路追踪最难的部分不是生成 ID，而是让 ID 能在服务之间自动传递。在微服务架构中，服务间的调用方式多种多样------HTTP/REST、RPC（Dubbo/gRPC）、消息队列（RocketMQ/Kafka）等。要让 Trace ID 和 Span ID 在这些通信边界上自动透传，离不开一个分布式上下文传播（Context Propagation） 机制。

以 HTTP 调用为例：当一个服务收到请求时，从请求头（通常是 b3 或 traceparent 头）解析上游传递过来的 Trace ID 和 Span ID，然后创建当前 Span，并将新生成的 Span ID 放入发往下游的请求头中。这样，一路透传下去，所有服务都能拿到同一个 Trace ID，从而将各自产生的日志数据串联到同一条链路上。

二、技术选型：从 Sleuth 到 OpenTelemetry

2.1 技术演进路线

Spring Cloud 生态在链路追踪方面经历了三个重要阶段：

第一阶段：Spring Cloud Sleuth + Zipkin

这是早期最主流的方案。Sleuth 自动对 RestTemplate、Feign、Zuul 等组件进行埋点，生成 Trace ID 和 Span ID 并写入日志，同时可配置上报到 Zipkin 做可视化展示。底层依赖 Brave（Zipkin 官方 Java 客户端）来实现上下文传播。

第二阶段：Spring Boot 3 + Micrometer Tracing

从 Spring Boot 3 开始，Spring Cloud Sleuth 正式被 Micrometer Tracing 取代。这一变化的核心动机是拥抱更开放、标准化的可观测性生态。Micrometer Tracing 提供了一个统一的门面（Facade），可以桥接到 Brave（Zipkin）和 OpenTelemetry 两种底层实现，让开发者不必绑死在特定的追踪系统上。

第三阶段：OpenTelemetry

如今，OpenTelemetry 已经成为行业事实标准。它是由 OpenTracing 和 OpenCensus 两大项目合并而成的 CNCF 项目，目前是 CNCF 中仅次于 Kubernetes 的第二大项目，约 48% 的组织已在使用或计划使用 OpenTelemetry。它不只做链路追踪，还统一了 Metrics 和 Logs 的数据模型和 SDK，可实现真正的"一次埋点，多处消费"。

2.2 方案对比

维度	Spring Cloud Sleuth	Micrometer Tracing	OpenTelemetry
定位	Spring 专属追踪方案	统一追踪门面	行业标准可观测性框架
当前状态	Spring Boot 3+ 中已弃用	推荐过渡方案	未来发展方向
覆盖范围	仅链路追踪	链路追踪（可桥接多种后端）	Traces + Metrics + Logs
厂商锁定	绑定 Spring 生态	较开放	完全厂商中立
内存占用	约 50-75MB	依赖桥接实现	默认配置较重，需优化
社区活跃度	维护模式	活跃	极活跃，CNCF 第二大项目

性能方面，有对比测试显示 OpenTelemetry 默认配置下内存占用约 75MB，而 Sleuth 功能相对单一，因此更轻量。但 OpenTelemetry 的优势在于功能全面和标准统一，轻量级不在于功能少，而在于配置优化得当。对于新项目，推荐直接使用 OpenTelemetry + Micrometer Tracing 桥接 的方案，兼顾标准化和 Spring 生态的便捷性。

2.3 链路追踪与采样策略

在引入链路追踪时，采样策略至关重要。如果每条链路都上报，会产生海量的存储和网络开销；如果采样太少，又可能错过关键的故障和慢请求信息。

常见的采样策略

策略	原理	适用场景
头部一致性采样	在请求入口处根据 Trace ID 做哈希决策，同一链路上所有环节采样决策一致	需要完整链路查看的场景
尾部采样	先暂存 Span，根据执行结果（慢、错误等）决定是否保留	优先采集异常链路
概率采样	按照固定百分比（如 1%）随机采样	高吞吐量、对成本敏感的场景
速率限制采样	限制每秒上报的 Span 数量	流量波动大的系统

在实际生产中，最推荐的组合方式是错慢采：正常请求按低概率（如 0.1%）采样，而包含错误（HTTP 5xx）或耗时超过阈值（如 3 秒）的请求强制保留整条链路。这种方式能用有限的存储成本，捕获最大价值的问题链路。

如果使用 OpenTelemetry，可以通过配置 OTEL_TRACES_SAMPLER 参数来快速设置采样模式，例如 parentbased_traceidratio:0.001 表示基于 Trace ID 的 0.1% 概率采样，且保证同一条链路上采样决策一致。

2.4 链路追踪与日志的关联

链路追踪的价值并不止于追踪本身，它真正的威力在于将三大支柱打通。最简单有效的关联方式，是在所有日志输出中自动带上 Trace ID：

java

// 通过 MDC 将 Trace ID 注入日志
import org.slf4j.MDC;
import io.opentelemetry.api.trace.Span;

// 在过滤器或拦截器中
Span currentSpan = Span.current();
String traceId = currentSpan.getSpanContext().getTraceId();
MDC.put("traceId", traceId);

配置日志格式（logback.xml）：

xml

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] traceId=%X{traceId} %-5level %logger{36} - %msg%n</pattern>

这样，每条日志都会打印 Trace ID。当用户报告某个订单支付失败时，只需从报错页面提取 Trace ID，就可以一瞬间从海量日志中 grep 出整条调用链的所有相关日志，结合 Zipkin/Jaeger 中的调用拓扑，定位耗时瓶颈和异常点。

三、实战：手把手接入链路追踪

下面以 Spring Boot 3 + Micrometer Tracing + OpenTelemetry + Jaeger 为例，完整演示链路追踪的接入过程。

3.1 环境准备

启动 Jaeger（用于接收和展示链路数据，推荐用 Docker）：

bash

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

成功后访问 http://localhost:16686 即可看到 Jaeger UI。

3.2 添加依赖

在 Spring Boot 3 工程的 pom.xml 中添加相关依赖：

xml

<properties>
    <micrometer-tracing.version>1.4.0</micrometer-tracing.version>
    <opentelemetry.version>1.46.0</opentelemetry.version>
</properties>

<dependencies>
    <!-- Micrometer Tracing 核心 -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
        <version>${micrometer-tracing.version}</version>
    </dependency>
    
    <!-- OpenTelemetry 导出器（对接 Jaeger） -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
        <version>${opentelemetry.version}</version>
    </dependency>
    
    <!-- Spring Boot Actuator 用于指标暴露 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    
    <!-- Web 相关依赖（RestTemplate 自动埋点） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

对于 Spring Boot 3 项目，spring-cloud-starter-sleuth 已不再推荐使用，官方建议用以上配置替代。

3.3 配置 application.yml

yaml

spring:
  application:
    name: order-service

management:
  tracing:
    sampling:
      probability: 0.1              # 10% 采样率，生产环境建议更低
    propagation:
      type: w3c                     # 使用 W3C tracecontext 标准
  zipkin:
    tracing:
      endpoint: http://localhost:4318/v1/traces  # Jaeger OTLP HTTP 端点
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
      compression: gzip

logging:
  pattern:
    # 日志中输出 traceId 和 spanId
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] traceId=%X{traceId} spanId=%X{spanId} %-5level %logger{36} - %msg%n"

3.4 主程序

主程序无需额外配置，Spring Boot 自动配置已处理好了埋点和上报的大部分工作。只需确保添加了 @SpringBootApplication 并启动应用即可，Micrometer 会自动对 RestClient、RestTemplate、WebClient、Controller 方法等进行埋点。

3.5 验证结果

启动两个微服务（如 order-service 和 inventory-service），调用它们之间的接口，打开 Jaeger UI（localhost:16686）。在 Search 页面选择服务名，即可看到完整的调用链路拓扑图，包括每个 Span 的耗时、元数据和调用关系。

3.6 自定义 Span

自动埋点虽然方便，但有时需要手动添加业务层面的 Span，比如记录某个复杂计算步骤的耗时：

java

import io.micrometer.tracing.Span;
import io.micrometer.tracing.Tracer;

@Service
public class OrderService {
    
    private final Tracer tracer;
    
    public OrderService(Tracer tracer) {
        this.tracer = tracer;
    }
    
    public void processOrder(Order order) {
        // 手动创建自定义 Span
        Span customSpan = tracer.nextSpan().name("calculate-discount").start();
        try (Tracer.SpanInScope ws = tracer.withSpan(customSpan)) {
            // 这里执行优惠计算逻辑
            discountCalculator.calculate(order);
        } finally {
            customSpan.end();
        }
        
        // 另一个自定义 Span
        Span dbSpan = tracer.nextSpan().name("save-order-db").start();
        try (Tracer.SpanInScope ws = tracer.withSpan(dbSpan)) {
            orderRepository.save(order);
        } finally {
            dbSpan.end();
        }
    }
}

3.7 在 OpenFeign 中传递 Trace 上下文

如果使用 OpenFeign 作为声明式 HTTP 客户端，确保开启 Feign 的链路自动传播（Spring Boot 自动配置已支持，无需额外代码，feign.Client 在 Bridge 下会自动从 current span 中提取上下文注入请求头）。如果遇到 Trace ID 丢失的问题，需要检查网关或负载均衡层是否正确转发了 traceparent 请求头。

四、生产环境最佳实践

4.1 必做：采样策略调优

全量采集在高并发场景下会极大增加存储压力和网络开销，对于可用存储空间有限的中小规模业务团队来说尤其不可持续。生产环境务必配置合适的采样策略：

yaml

management:
  tracing:
    sampling:
      probability: 0.001   # 千分之一采样，适合中高流量

也可以实现自定义Sampler，对带有特定标识的请求（如VIP客户、内部测试）进行全量采样。

如何在采样前判断 "此请求是否需要全量采集"？

不同的采样模式决定了是否能动态决定采样结果：

• 头部采样：请求入口处能提前获知的信息（VIP 头、请求路径、特定参数等）可以在链路生成前用于决策；

• 尾部采样：可对已产生的 Span 进行事后评估，根据执行耗时、报错等状态决定保留或丢弃。

对于超过性能阈值（如响应时间大于3秒）或包含特定错误码的请求，使用尾部采样强制保留整条链路，能确保错慢链路被有效捕获。实现时需在 OpenTelemetry Collector 中配置 tail_sampling 处理器。

4.2 推荐：自定义线程池的上下文传递

在异步编程中，Trace 上下文不会自动传递到新线程。使用 @Async 时务必自定义线程池并包装 TaskDecorator：

java

@Bean
public ThreadPoolTaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(5);
    executor.setMaxPoolSize(10);
    executor.setTaskDecorator(new TraceableTaskDecorator());  // 传递上下文
    executor.initialize();
    return executor;
}

// 自定义 TaskDecorator 实现
public class TraceableTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        // 从当前线程获取 Trace 上下文
        Map<String, String> contextMap = TraceContextHolder.getCurrentContext();
        return () -> {
            try {
                TraceContextHolder.setCurrentContext(contextMap);
                runnable.run();
            } finally {
                TraceContextHolder.clear();
            }
        };
    }
}

如果不这样做，异步线程中生成的 Span 将无法与父 Trace 关联，导致链路断裂。

4.3 注意：消息队列的上下文注入

对于 RocketMQ、Kafka 等消息队列场景，发送消息时需在消息头中手动注入 Trace 上下文：

java

// 发送时注入
Span currentSpan = tracer.currentSpan();
Message<String> msg = MessageBuilder.withPayload(data)
    .setHeader("traceId", currentSpan.context().traceId())
    .setHeader("spanId", currentSpan.context().spanId())
    .build();

// 消费时解析
@KafkaListener
public void consume(ConsumerRecord<String,String> record) {
    String traceId = record.headers().lastHeader("traceId").value();
    // 在此线程中初始化 Trace 上下文
    tracer.withSpan(...).run(() -> { ... });
}

4.4 强烈推荐：日志与链路联动

结合 MDC，在每条日志中输出 Trace ID 和 Span ID，这样在排查问题时可以从链路平台跳转到具体日志，也可以从日志反查链路详情。配置方式同前文的 logging pattern，标准输出示例：

text

2026-04-26 10:00:01.123 [http-nio-8080-exec-1] traceId=abc123xyz spanId=def456 INFO  com.example.OrderController - 收到下单请求
2026-04-26 10:00:01.200 [http-nio-8080-exec-1] traceId=abc123xyz spanId=ghi789 INFO  com.example.InventoryService - 扣减库存成功

配合 ELK 或 Loki 等日志系统，按 traceId 聚合所有日志即可获得完整链路详情。

4.5 重要：成本控制

手段	说明
采样率调低	一般请求 0.1% - 1% 足够
Span 数量控制	避免循环内存量 Span（如批量处理数千条记录时，不要为每条记录创建 Span）
属性精简	只上报必要的标签（Tag/Baggage），避免存储大对象或超长字符串

五、常见问题排查

Q1：Jaeger/Zipkin 上看不到数据？

• 检查防火墙和端口（Jaeger OTLP HTTP 端口 4318，gRPC 端口 4317）

• 查看应用日志中是否有上报错误

• 确认采样率不是 0

Q2：Trace 在某些环节中断了（丢失传播）

• 检查网关或负载均衡层是否转发了 traceparent 头

• 检查自定义 HTTP 客户端是否手动清空了请求头

• 多协议调用场景，检查是否支持多协议间上下文转换（如 HTTP 调用 gRPC）

• 确认依赖的 micrometer-tracing-bridge-otel 被正确引入

Q3：跨线程/异步丢失链路

Spring 的 @Async 默认不会传递 Trace 上下文。解决方案：

• 方案一：实现 TaskDecorator（如上文 4.2 节示例，推荐）

• 方案二：手动在父子线程间传递 TraceContext（通过 ThreadLocal 变量，但需自行管理生命周期）

Q4：迁移时发现 Span 重复上报或丢失

当同时存在 micrometer-tracing 和原生 opentelemetry-javaagent 时，Span 可能被上报两次。建议二选一，不要混用。从 Sleuth 迁移时，注意移除 Sleuth 依赖并使用官方迁移工具，不要保留多个桥接依赖。

总结

方面	推荐做法
新项目选型	Spring Boot 3 + Micrometer Tracing + OpenTelemetry
采样策略	千分之一到百分之一，错慢全采
核心配置	采样率 + W3C propagation + Jaeger/Zipkin 端点
异步处理	TaskDecorator 包装线程池
日志关联	MDC 输出 traceId，日志平台按 traceId 聚合
成本控制	精简单 Span，合理采样，避免全量

链路追踪是微服务架构下定位问题的核心手段。做好链路追踪，当系统出现故障时，你不再是"在几十台服务器日志里大海捞针"，而是打开链路平台，输入 Trace ID，整个调用链一清二楚------慢在哪个环节、错在哪个服务、异常堆栈是什么，一目了然。它与指标（Metrics）的宏观监控能力、日志（Logging）的逐条排查能力相互交错，形成完整的可观测性数据闭环。

希望这篇从原理到实战的总结能帮你真正落地分布式链路追踪。欢迎在评论区分享你在链路追踪中遇到的坑或经验～