Quick Reference

trace id 排障速查

同一个值,一路留痕。知道它落在哪几处、每处叫什么名字,排障就从「翻七个服务」变成「搜一个字符串」。

六个落点

在哪
叫什么
备注
浏览器 F12 响应头
Trace-Id
你的抓取入口。常量在 AuthProvider.TRACE_ID
服务间请求头
LogTraceUtil.TRACE_ID
网关写入,往下游透传
业务服务日志行
[%X{tid}]
SkyWalking MDC toolkit,每行都带
网关日志行
%X{traceId:-traceId}
打的是占位符,不是真值(见下)
数据库
vcm_user_optlog.trace_id
操作日志落库时写入
鼎流后台
「链路id」列
监控 → 日志(错误 / 常规 / 接口)

诊断信号表

你看到的
意思
下一步
响应头有 Trace-Id
一切正常
抄下来去日志中心搜
日志里 [TID: N/A]
SkyWalking 探针没生效
先查 agent 挂载,别怀疑业务代码
网关日志里字面量 traceId
正常。网关刻意不落 MDC
去下游服务日志看真值
前半段有、支付段断
跨异步线程,上下文没还原
换业务键(结算 id / 运单号)续查
值像业务编码而非长串
可能拿错了字段(见陷阱一)
确认取的是 LogTraceUtil.getTraceId()

取值的四级兜底

网关 TraceIdRequestFilter 按顺序取,前一级拿不到才降级。这解释了为什么同一个系统里 trace id 格式不统一:

  1. SkyWalking 探针的 traceId

    反射从 exchange 上摘 getSkyWalkingDynamicField。探针在跑时走这条。

  2. 请求头里已有的

    上游系统或 App 已经生成过,网关就接管不重造。

  3. ThreadLocal 上下文里的

    LogTraceUtil.getContextTraceId()。

  4. 雪花算法兜底生成

    TraceId.worker.nextId(),plumelog 的。是一串纯数字——看到纯数字就说明前三级都没命中,探针大概率没生效。

陷阱一:同名不同物

LogTraceUtil.getTraceId()

真链路 ID,用来串日志。

wmsAppointmentDTO.setTraceId(…)

不是链路 ID,装的是 dbOrder.getOrderNo(),作用是 WMS 接口的幂等去重键。

判断法 看赋的值,不看字段名。运单号是有规律的业务编码,链路 ID 是长数字或十六进制串——形状不一样。

陷阱二:MQ 之后链路断

logback 官方:MDC 按线程管理,「工作线程并不总能从发起线程继承到 MDC 的副本」。所以跨线程必须手工传。

accountFreightPay.setTraceId(LogTraceUtil.getTraceId()); // 生产端传了

但消费端 AccountWaybillFreightPayMQListener / AccountPaymentServiceImpl 没读这个字段。2026-09-22 已在分支 fix/mq-traceid-logback-zhongji 用 LogTraceUtil.addTraceId() 接回,待提测。

结论 走 MQ 的异步动作(运费支付典型),trace id 只查到「发消息」那一刻。这是结构性缺陷,不是你不会查。状态:未修复,可提研发。

四条记住就够

  1. 抓它去响应头,不是请求头。
  2. 网关日志里那个是占位符,真值在下游服务。
  3. TID: N/A = 探针问题,不是代码问题。
  4. 走 MQ 就断,换业务键接着查。

配套课程:一次请求的身份证  · 主源:Logback 官方 · MDC  · SkyWalking logback toolkit