分布式追踪 | devexamples

分布式追踪用贯穿请求的 trace id 和 span 树还原跨服务调用路径，定位延迟与错误归属。

一条 trace 就是一条时间线

请求进入系统后获得一个 trace id。每个服务创建 span、记录自己的工作，并把追踪上下文传给下游调用。后端把 span 组装成树，最慢的 span 和报错的 span 指出应该调查的位置。

trace 4bf92f...
  gateway        120 ms
    orders       95 ms
      postgres   70 ms
      payments   20 ms

W3C 的 traceparent 头携带 trace id、父 span id 和采样决策。要通过 HTTP 客户端、消息头和后台任务传播它。每个跳点都新开 trace 的服务会破坏时间线。

高流量下追踪每个请求非常昂贵。头部采样在开始时决定，简单但可能漏掉罕见故障；尾部采样先缓冲 span，只保留慢的或含错误的 trace，代价是基础设施。无论哪种方式，都要把采样决策写入上下文，让所有服务达成一致。

对入站请求、出站调用、数据库查询和队列操作埋点。添加有助于诊断的属性，如路由、状态码和依赖名，但要避免密钥和无界用户数据。用 trace id 关联日志，在支持时用 exemplar 关联指标。

当请求跨越多个服务，且延迟或故障归属不清时，使用分布式追踪。优点是端到端可见性和精确定位；代价是埋点、存储成本和采样复杂度。与指标相比，trace 解释单个请求；与日志相比，它不用读几千行就能展示调用路径和时序。