Jaeger实战：从支付超时排查讲透分布式追踪与链路排查

凌晨12点，手机震了三次，心里一紧。登录后台一看，支付回调接口的P99延迟飙到了5秒，正常水位是200毫秒。用户付款成功但页面迟迟不跳转，客服群里已经炸了。我做了这么多年后端，最怕这种"多个服务都正常，但链路上不知道哪个环节慢半拍"的问题。幸好这次有Jaeger。输入网关日志里捞出的trace_id，一键查询，30秒定位到外部渠道商接口异常。整个排查过程没有去翻一台台服务器日志，也没有靠猜。这个"救命工具"就是分布式追踪系统Jaeger，本文我会把它的核心模型、采样策略、部署选型、性能影响和实战经验一次讲透。

1. 一次支付回调超时的排查实录

1.1 从报警到定位：完整还原排查链路

先交代一下背景。我们用的技术栈是Spring Cloud，核心交易链路涉及网关、订单服务、支付服务、外部渠道商回调。出问题那晚，报警规则是"支付回调接口P99超过3秒持续5分钟"，阈值一破，值班手机就响了。

第一步，我没有直接登录服务器，而是先去Nginx访问日志里捞慢请求。理由很简单：流量入口的访问日志最全，而且里面有网关在入口处注入的trace_id，形如8a3d5f2e...这一长串十六进制。有了它，就相当于拿到了这条请求在系统中的"身份证号"。

第二步，打开Jaeger UI，搜索框粘贴这个trace_id，回车。一条完成的调用链在时间线上舒展开来，从网关到订单服务再到支付服务，一直到外部渠道商HTTP调用。整条链路总耗时4.7秒，内部服务自身的逻辑只花了280毫秒，剩下的3.9秒全部压在了那个外部HTTP调用上。

第三步，点开那个外部调用的Span，看Tags。方法、URL、状态码、响应体大小全都记录在案。进一步确认是渠道商接口的响应变慢，而不是我们超时时间设得太短导致误报。

第四步，打开Jaeger的依赖分析页（Service Dependency Graph），看到这个外部依赖的调用量和错误率在最近15分钟明显攀升，坐实了"上游服务问题"，直接发工单联系渠道商处理。

整个定位过程不到5分钟。对比以前没有链路追踪时的"复盘会"——开发说网关没问题，网关说订单服务正常，订单服务说支付服务没报错，支付服务说对方返回慢——你说气不气。

1.2 为什么Nginx网关层要生成trace_id

很多同学问过：为什么不直接在业务服务里生成trace_id，非得在网关生成？核心原因是"入口生成、全链共享"。网关是流量的必经之路，所有请求都从这里进来。在这层生成一个全局唯一的ID，通过HTTP Header传给下游，后面每一个服务都把这个ID原样透传下去，最终就能保证一次用户请求产生的所有Span都属于同一条Trace。

Jaeger原生使用uber-trace-id这个Header，格式是{trace-id}:{span-id}:{parent-span-id}:{flags}。现在业界标准是W3C的traceparent，形如00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01，Jaeger早已兼容。

提示：如果请求进来时没有携带任何trace上下文，Jaeger SDK会自动生成一个新的TraceId，自己成为Root Span。这就是为什么你能在UI里看到一些"孤立"的Trace——它可能是外部直接调用，没走网关导致的。

2. 核心数据模型：Span、Trace与上下文传递

2.1 Span的字段结构

分布式追踪里，一个Trace由若干个Span组成，Span是链路中的最小工作单元。可以把它理解成电视剧里的一集：Trace是整部剧，Span是每一集，而References（引用关系）决定了集与集之间的播放顺序。

一个Span，核心字段如下表：

Tags的设计逻辑值得多说一句。Tags是"可索引的维度"，UI里支持按tag名=值做Search，比如查http.status_code=500就能筛选出所有返回500的Span。但注意，tags不要塞太多大对象，只放那些用于查询和定位的键值，比如订单ID、用户ID、HTTP状态码。想记录业务细节，用logs更合适。

2.2 父子关系与FollowsFrom

Span之间最常用的引用关系是ChildOf，语义是"子Span的完整生命周期取决于父Span"。比如支付回调接口（父Span）内部发起了数据库查询（子Span），数据库查询的结束时间必然早于父Span。

另一种引用关系是FollowsFrom，很多初学者不知道。它的语义是"父Span触发子Span，但不等待它结束"。典型场景是异步消息：支付成功后，把短信通知的消息丢进MQ，父Span可以直接返回，短信服务消费消息时父Span早就结束了。如果错误地把这种关系建模成ChildOf，UI上会出现"子Span持续时间比父Span长"这种违反直觉的视图。

在Jaeger UI里，这两种关系分别展示为Trace Graph（带箭头的依赖图）和Call Tree（调用树）。Call Tree适合看耗时分布，Trace Graph适合看拓扑依赖。排查性能问题优先看Call Tree，排查架构问题看Trace Graph。

2.3 上下文传递：跨进程与跨线程

分布式追踪能串成链路的本质，是SpanContext在进程间和线程间的传递。SpanContext是一个轻量级对象，只包含traceId、spanId、采样标记等必要信息，它不携带业务数据，但可以被序列化后放到Header里传出去。

跨进程传递的标准姿势是inject/extract。HTTP场景下，服务A在发起调用前，把当前SpanContext注入到HTTP Header里；服务B收到请求后，从Header里提取SpanContext，创建子Span，这样链路就接上了。

跨线程传递是另一个坑。Java里使用线程池做异步任务时，子线程默认不会继承父线程的TraceContext。很多团队第一次接入Jaeger后，在UI里发现"一次请求被拆成了好几条Trace"，就是异步场景上下文丢失导致的。

解决办法是把当前Span的Context显式透传给子线程。以Java为例：

java复制SpanContext spanContext = tracer.activeSpan().context();
executor.submit(() -> {
    // 在新线程中将spanContext作为parent创建子span
    Span childSpan = tracer.buildSpan("async-task")
            .asChildOf(spanContext)
            .start();
    // 业务逻辑...
    childSpan.finish();
});

也可以用官方推荐的Scope机制，本质一样。Python的contextvars、Go的context.WithValue同理，思路都是"手动把trace上下文捞出来，塞进新线程/协程能读到的地方"。

3. 采样策略的权衡艺术：从固定比例到尾采样

3.1 为什么不能一直100%全采

如果服务QPS是2000，一次请求平均产生30个Span，一天下来就是50亿级别的Span。ES集群的写入和存储成本直接爆炸，磁盘再便宜也扛不住这个量级。所以生产环境必须做采样——不是"丢失数据"，而是"有策略地保留数据"。

最基础的是固定比例采样。Java SDK里配置：

java复制JaegerTracer.Builder builder = new JaegerTracer.Builder("order-service")
    .withSampler(new ProbabilisticSampler(0.1))
    .withReporter(new RemoteReporter.Builder()
        .withSender(new UdpSender("jaeger-agent", 6831, 0))
        .build());

意思是"每个Trace有10%的概率被采样保存"。这个方案简单直接，但有一个致命缺陷：采样决策在链路入口就定了，而这条链路是否包含错误、是否超过耗时阈值，在当时根本不知道。一个恰好被概率丢弃的Trace，可能就是最需要排查的那条。

3.2 限速采样与远程采样

为了解决概率采样在流量突发时的不可控性，Jaeger提供限速采样（RateLimiting），每秒最多采集N条Trace。这样即使QPS瞬间冲到5000，存储压力也被锁死在预设水位。代价是流量低谷期样本量不足，可能连看趋势都不够。

远程采样（Remote Sampling）更灵活：Collector集中下发采样策略，不同服务可以配置不同采样率。比如订单服务10%、日志服务1%，修改策略时不用重启服务，SDK定期拉取即可。这在微服务规模变大后几乎是刚需，否则30个服务就得改30份配置。

3.3 尾部采样：为错误链路兜底

低流量系统用head-based采样还有个尴尬场景：一天可能就100条请求，你设置了10%采样率，结果那条报错的请求恰好被丢弃——追踪系统最该捕捉的东西反而丢了。

真正稳妥的方案叫tail-based sampling（尾部采样）。思路是：SDK端全量上报（或高概率上报），在OpenTelemetry Collector侧根据完整链路信息决定最终是否保存。规则可以很灵活："链路中任意Span包含error=true就保留"、"总耗时超过2秒就保留"、"特定服务名的调用保留"。

Jaeger本身没有内置tail sampling，需要借助OpenTelemetry Collector的tail_sampling处理器。配置片段如下：

yaml复制processors:
  tail_sampling:
    policies:
      - name: errors
        type: status_code
        status_code: {status_codes: [ERROR]}
      - name: slow-traces
        type: latency
        latency: {threshold_ms: 2000}

代价也是明显的：客户端到Collector之间要全量传输数据，带宽和Collector内存消耗变大。它本质是"用计算换准确性"，适合核心交易链路、支付场景这类"宁可多花带宽也不能漏掉一条错误链路"的业务。

注意：tail sampling的判断是"链路结束之后"做的，所以Collector必须能缓存一段时间的链路数据，内存要按峰值流量估算，不然高并发下会OOM。

3.4 不同场景的采样率参考

结合我自己的实践，给出一个采样率参考表，可直接抄作业：

Go和Python的采样配置也很常用，顺手给出：

go复制cfg := jaegerconfig.Configuration{
    ServiceName: "order-service",
    Sampler: &jaegerconfig.SamplerConfig{
        Type:  jaeger.SamplerTypeProbabilistic,
        Param: 0.1,
    },
}

python复制from jaeger_client import Config
config = Config(
    config={
        'sampler': {'type': 'probabilistic', 'param': 0.1},
        'logging': True,
    },
    service_name='order-service',
)

4. 存储选型与部署形态：从单机到微服务化

4.1 Jaeger的运行时角色

Jaeger体系里有几个角色需要分清：

• Client SDK：埋在业务代码里，负责产生Span并上报。
• Agent：早期架构里的本地代理，SDK通过UDP把数据先发给同机的Agent，再由Agent转发给Collector。现在不推荐再加这一跳。
• Collector：负责接收、校验、写入存储，无状态，可水平扩容。
• Query：提供Web UI和API查询服务，无状态。
• Storage：后端存储，决定整个系统的上限。

4.2 三种部署形态

All-in-one：本地调试最方便，一个容器搞定。命令是：

bash复制docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:1.60.0

UI访问http://localhost:16686，数据默认存内存或Badger。适合本地联调，不适合生产。小团队如果只是页面调用链展示，每天几百条Trace也可以凑合用，但建议还是上ES。

单机生产：Collector + ES + Query，用Docker Compose或K8s单节点部署。我给了很多团队一个最小化配置，这个配置在本地是能直接跑起来的：

yaml复制version: '3'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.10
    environment:
      - discovery.type=single-node
  jaeger-collector:
    image: jaegertracing/jaeger-collector:1.60.0
    command: ["--es.server-urls=http://elasticsearch:9200", "--es.num-shards=3", "--es.num-replicas=1"]
    environment:
      - SPAN_STORAGE_TYPE=elasticsearch
    ports:
      - "4317:4317"
      - "14250:14250"
      - "14268:14268"
  jaeger-query:
    image: jaegertracing/jaeger-query:1.60.0
    command: ["--es.server-urls=http://elasticsearch:9200"]
    environment:
      - SPAN_STORAGE_TYPE=elasticsearch
    ports:
      - "16686:16686"

新手最容易漏的是SPAN_STORAGE_TYPE=elasticsearch这个环境变量，不设的话Jaeger默认用的还是内存存储，重启全丢。

生产微服务化：多Collector跑在K8s里由HPA自动扩缩容，数据先写入Kafka做缓冲，再由独立的消费程序写入ES集群，Query前面挂负载均衡。这适合日请求量千万级以上的团队。Kafka的引入主要价值是削峰填谷——流量尖峰时Collector来不及写ES，先让Kafka扛住，消费者按ES能承受的速度慢慢写。

4.3 存储选型对比

ES虽然最多人用，但它不是银弹。写入性能极其依赖索引规划，如果分片数、副本数设得不准，流量一高就可能出现写入拒绝。我建议按照日增数据量提前设置分片数，并配置索引生命周期管理（ILM）。基本思路是：trace索引按天滚动，保留14天热数据，超过14天下沉到warm节点，超过30天删除。这样可以防止ES集群被历史数据拖垮。

4.4 高可用部署的几个关键点

第一，Collector必须无状态。不要往Collector容器里挂任何本地磁盘存储，所有状态都放ES或Kafka里，这样HPA扩容缩容才安全。

第二，Query前面加负载均衡。Query本身是无状态的，多副本部署后用Service暴露，流量分布在多个实例之间。

第三，存储是单点的话，前面全白搭。ES至少三节点起步，并且要关注分片健康状态。见过不少团队Jaeger集群所有组件都高可用，结果ES磁盘被写满，整个链路追踪系统直接瘫痪，排查问题时发现"查不了"。

第四，早期Jaeger架构里的Agent层，现在不建议再用了。官方已经明确推荐SDK通过OTLP/gRPC直连Collector，减少一跳，省去UDP丢包的隐患。

5. 埋点性能影响与全链路优化

5.1 埋点到底拖不拖慢业务

这是每个技术负责人都会问的问题。Jaeger SDK在正常配置下，单条Span的创建+序列化+上报开销在微秒级，相比业务逻辑动辄几十毫秒的耗时几乎可以忽略。我实测过：在2C4G的普通云主机上，10%采样率下，业务P99延迟增长不超过1%。

但有几个前提：批量上报必须开启（SDK默认就是批量异步）、上报通道健康、采样率不是100%。如果100%采样同时Collector压力大、上报队列堆积，影响会被放大到5%~10%。所以生产环境的关注点不是"要不要埋点"，而是"上报链路是否健康"。

5.2 一个隐蔽的性能陷阱：Span不闭合

服务内存缓慢上涨、上报延迟越来越高、SDK队列被打满，这种问题排查起来特别烧脑。最常见的隐蔽原因之一，是Span没有调用finish()。

看一段反例代码：

java复制Span span = tracer.buildSpan("processOrder").start();
// 业务逻辑...
if (condition) {
    throw new RuntimeException("boom");
}
span.finish(); // 异常路径直接跳过了这一行

异常抛出时，finish()没执行，这个Span永远处于"未完成"状态，被SDK缓存在内存里。等并发量一上来，内存和队列都遭殃。解决方式很简单：用try-with-resources或者在finally块里保证闭合。Java SDK更推荐startActive(true)模式，作用域退出时自动finish：

java复制try (Scope scope = tracer.buildSpan("processOrder").startActive(true)) {
    // 业务逻辑
    scope.span().setTag("order.id", orderId);
    scope.span().log("order.started");
    callPaymentService();
} catch (Exception e) {
    // 异常路径也要记录
    throw e;
}

排查这类问题有个小技巧：在Jaeger UI里搜索duration异常大的Root Span，如果发现一堆长时间挂起的空Span，基本就是某段代码忘了闭合。

5.3 全链路优化的几个实操建议

• 开启压缩传输。OTLP/gRPC默认支持gzip压缩，带宽成本能降不少。
• 不要在上报层做重试。SDK上报失败时，重试会造成数据乱序和重复，而且被采样的Trace价值有限。正确的做法是确保SDK队列足够大，Collector端做幂等去重。
• 采样率分开配。核心支付链路可以用10%~20%，低价值的查询或日志类接口直接1%，甚至0。不是所有服务都需要同样高的采样率。
• 监控Collector队列深度。一旦持续增长，说明消费能力跟不上，要么扩容Collector，要么检查ES写入是否出现拒绝。

6. Jaeger与OpenTelemetry：演进方向与生态集成

6.1 从jaeger-client到OTel的统一

早期接Jaeger，是直接在代码里引入jaeger-client，产生Jaeger格式的Span数据，通过Thrift协议上报。这套模式现在依然能跑，但已经不是最优解了。

OpenTelemetry（OTel）已经成为可观测性领域的事实标准，它统一了Metrics、Logs、Traces三类数据的生成。现在的推荐架构是：应用通过OTel SDK产生OTLP格式数据，Jaeger作为后端接收OTLP并存储展示。Jaeger从1.35版本开始原生支持OTLP接收，到了Jaeger v2，底层Collector直接改为OpenTelemetry Collector，算是彻底转向。

对使用者来说，最直观的变化是：埋点代码不用绑死任何一个厂商。今天后端用Jaeger，明天想换成其他兼容OTLP的平台，SDK不用动，只改上报地址就行。

6.2 零代码侵入：Java Agent真香

对于绝大多数业务服务，最简单的方式是直接用OTel Java Agent，连代码都不用改：

bash复制java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.service.name=order-service \
     -Dotel.exporter.otlp.endpoint=http://jaeger-collector:4317 \
     -jar order-service.jar

这个Agent会自动为Spring Boot、Netty、Dubbo、JDBC、Redis、Kafka、RabbitMQ等主流框架插桩，请求进来时自动生成Trace，调用外部服务时自动传递上下文。我团队新接手的服务，基本都先上Agent，跑通链路，之后如果有特殊业务需求再用Manual Instrumentation补埋点。既快又稳，还能避免埋点里的低级错误。

6.3 打通日志与Trace：排查效率翻倍

链路追踪和日志系统如果各管各的，排查问题依然要来回切换。正确做法是：把trace_id和span_id注入到应用日志的MDC里，日志系统里带着trace_id，排查时用日志里的trace_id一键跳到Jaeger链路详情。

Logback配置示例：

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

OTel Java Agent较新版本默认开启trace_id/span_id的MDC注入，加上这个pattern即可。生产环境的实战效果是：用户报障时，客服给一个单号，先搜日志找到trace_id，再跳到Jaeger看这条请求的全部调用细节。从"大海捞针"变成"精确制导"。

6.4 生态联动与常见误区

Grafana可以直接配置Jaeger数据源，在Grafana里完成Trace检索和详情页查看。如果团队同时用了Prometheus和Loki，那就是标准的metrics-logs-traces三端联动：Prometheus负责告警和趋势，日志负责业务细节，Trace负责定位全链路。

需要纠正一个常见误区：不要把告警直接挂在Jaeger上。采样后的Trace数据缺失率很高，根本不具备稳定告警的条件。告警应该靠Metrics，比如Prometheus的RED指标（Rate、Errors、Duration），Trace用来在告警发生后做二次定位。业务指标与链路数据各司其职，才是合理的可观测性设计。

7. 常见坑位速查与经验沉淀

最后整理一些高频问题的速查表，都是我踩过或帮别人排查过的：

对云原生环境多说一句：时钟同步特别容易被忽略。容器启动时镜像自带的时间可能与实际差很多，新Pod如果没有挂载宿主机的/etc/localtime，很可能会出现"子Span结束时间早于父Span"这种荒唐数据。在Jaeger UI里看到这种迹象，先查NTP，别一头扎进业务代码里找bug。

还有一个日常维护建议：定好Tag命名规范。团队里如果一个人用http.code，另一个人用http_status_code，UI搜索时就会漏查。我自己的习惯是统一采用OTel语义约定（semantic conventions），比如HTTP状态码必须叫http.status_code，服务名不带环境后缀，环境信息用Tag区分。

我用Jaeger这几年，最大的感受是：分布式追踪不是"锦上添花"的可观测性工具，而是复杂系统里救火用的强光手电。生产环境出问题，总不能用"所有服务都查一遍"这种方式赌运气。有了trace_id，问题的搜索空间从"所有服务所有时刻"收敛到"一条请求一条链路"，效率提升了不止一个量级。

如果你也在用Jaeger或者刚准备接入，欢迎聊聊你们踩过最诡异的链路断裂案例，或者最希望Jaeger改进的功能。踩坑经验这种东西，每次交流都可能有新收获。