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 格式不统一:
-
SkyWalking 探针的 traceId
反射从
exchange上摘getSkyWalkingDynamicField。探针在跑时走这条。 -
请求头里已有的
上游系统或 App 已经生成过,网关就接管不重造。
-
ThreadLocal 上下文里的
LogTraceUtil.getContextTraceId()。 -
雪花算法兜底生成
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 只查到「发消息」那一刻。这是结构性缺陷,不是你不会查。状态:未修复,可提研发。
四条记住就够
- 抓它去响应头,不是请求头。
- 网关日志里那个是占位符,真值在下游服务。
TID: N/A= 探针问题,不是代码问题。- 走 MQ 就断,换业务键接着查。
配套课程:一次请求的身份证 · 主源:Logback 官方 · MDC · SkyWalking logback toolkit