S17-A02 · 链路追踪与可观测性

适用读者：一次请求跨 8 个服务、不知道慢在哪的人。
前置：S17-A01。
覆盖旧文：410（链路追踪，417 点）。
覆盖扩展：E-S17-012（trace/span 传播）。
上一篇：S17-A01 · 服务治理：限流、熔断、降级
下一篇：S17-A03 · Netty 与网络编程模型。

1. 一句话结论

链路追踪的本质是"把一个 traceId 一路带下去，每个服务记一段 span"。没有传播，就没有链路。

traceId=abc123
 ├─ span: gateway        12ms
 ├─ span: order-service  48ms
 │    └─ span: mysql     31ms
 └─ span: pay-service    22ms

2. 三个概念（E-S17-012）

概念	说明
traceId	全局唯一，贯穿整个请求
spanId	单个环节的 id
parentSpanId	谁调用的（构成树）

传播方式：

协议	载体
HTTP	`traceparent` 头（W3C Trace Context）
MQ	消息属性
线程池/异步	手动传递（最易丢）

"为什么异步会丢"：traceId 存在 ThreadLocal（S05-B04）——跨线程要显式复制。

3. 三件套：日志、指标、追踪

支柱	回答的问题
日志	发生了什么
指标	整体趋势（QPS/错误率/延迟分位）
追踪	这一次请求慢在哪

判据："你能回答"P99 为什么涨了"吗？" 只有指标不够，需要追踪定位到具体 span。

4. 采样：不采全量的原因与代价

采样方式	说明
固定比例（1%）	简单，可能漏掉长尾
尾部采样	只保留慢/错的（更有用）
全量	成本极高

"采样会漏掉问题吗"：会——所以错误与慢请求要强制保留（尾部采样正是为此）。

5. 落地清单

项	要求
traceId 注入	网关统一生成（S17-B04）
日志格式	每条日志带 traceId（S07-B06 的 MDC）
跨服务	HTTP 头/MQ 属性透传
异步	线程池装饰器复制上下文
存储	采样 + 保留期（成本控制）

6. 五个误区

误区	真相
"有日志就有链路"	缺 traceId 无法串联
"全量采集更好"	成本爆炸
"异步不影响追踪"	ThreadLocal 会丢
"只看平均值就行"	要看 P99
"追踪能替代指标"	两者互补

7. 自检（架构师版）

traceId/spanId/parentSpanId 的关系？
跨服务与跨线程分别怎么传播？
三支柱各回答什么？
为什么用尾部采样？
落地清单里最容易漏哪条？

8. 下一篇

S17-A03 · Netty 与网络编程模型

追踪讲完，最后一篇技术篇：为什么 Netty 能撑高并发。

本篇属于系列《S17 · 分布式与消息队列》。旧文来源：A-410；扩展点 E-S17-012。