一次请求的
身份证
前四课都在读静态的代码——文件、分支、冲突。这一课换一头:代码跑起来之后留下的痕迹。学会用 trace id,你就能从「用户说支付失败了」直接跳到「是 vcm-user 这一行报的错」,不用翻七个服务的日志。
先看东西在哪:一次请求走三站
trace id 不是一个存在某处的字段,而是同一个值在一路上反复留下的痕迹。你要建立的是这张位置图——哪站留了痕、留在哪、你从哪伸手去拿:
浏览器 / 货主端 App
请求发出去,响应回来。响应头里带着这次请求的 trace id——这是你唯一不用登服务器就能拿到它的地方。
常量定义在 AuthProvider.TRACE_ID,值就是字符串 "Trace-Id"。
vcm-gateway 网关
trace id 在这里被生成或被接管,然后塞进请求头。但网关故意不把它放进自己的日志上下文——源码里那行是注释掉的,注释写明「网关不在 ThreadLocal 上下文添加 traceId,用于优化性能」。
因为没放进上下文,这里打出来的是兜底占位字符串,不是真值。看到网关日志里写着字面量 traceId,那是正常的,不是坏了。
业务服务 vcm-order / vcm-user / …
这里才是你查日志时真正能搜到东西的地方。同一个 trace id 会落在三处:
SkyWalking 官方 MDC toolkit 打的。每一行都带,所以搜它比搜订单号命中率高得多。
操作日志落库时用 LogTraceUtil.getTraceId() 取值写进去。
生产端手工塞进去了,但消费端没读——详见下面「陷阱二」。
查看入口:鼎流后台「监控 → 日志」下的几个页面(错误日志 / 常规日志 / 接口日志),都有一列中文标签叫 「链路id」。那一列就是 trace id——名字不一样,东西是同一个。
用户报障,你要抓这次请求的 trace id。在浏览器 F12 里看哪个?
为什么它能打进日志:MDC
日志行里那个 %X{tid} 不是魔法。MDC(Mapped Diagnostic Context)是 logback 的机制,官方定义是一种「为每一条日志请求盖上唯一戳记」的技术:把上下文信息放进 MDC,logback 就能自动带进每一行日志。
%X 就是从 MDC 里取值的占位符,%X{tid} = 取 MDC 里 key 为 tid 的那个值。
见 Logback 官方手册 · Mapped Diagnostic Context
诊断信号:看到什么,说明什么
排障时你会撞见这几种情况。能一眼判断它是「真问题」还是「正常现象」,就省掉大半冤枉路:
Trace-Id[TID: N/A]traceIdTID: N/A 这个具体输出来自 SkyWalking 官方 logback toolkit 文档——本项目 vcm-log/logback-spring.xml 用的正是官方那个 TraceIdMDCPatternLogbackLayout,pattern 和官方示例一字不差。
陷阱一:有个同名不同物的字段
项目里有两个都叫 traceId 的东西,用途毫无关系。认错了就会拿着运单号去日志中心白搜一场:
LogTraceUtil.getTraceId()
真的链路 ID。用来串日志。值是 SkyWalking 的 traceId 或雪花算法生成的数字。
wmsAppointmentDTO.setTraceId(…)
不是链路 ID。装的是 dbOrder.getOrderNo()——运单号,作用是给 WMS 接口做幂等去重键。源码注释写着「幂等标识,使用traceId」,但塞进去的是订单号。
setTraceId(dbOrder.getOrderNo()) 一眼就能看出装的是业务单号——形状不对(运单号是有规律的业务编码,链路 ID 是长数字或十六进制串)。
陷阱二:支付走 MQ 之后,链路是断的
回到那句「MDC 按线程管理」。ThreadLocal 过不了线程边界,logback 官方把这个坑说得很直白:
「工作线程并不总能从发起线程继承到 MDC 的副本。使用 java.util.concurrent.Executors 管理线程时就是这种情况。」
—— Logback 官方手册 · MDC。官方给的解法是手工 MDC.getCopyOfContextMap() 再 setContextMap()。
所以运费结算这条链,生产端确实做对了一半——它把 trace id 手工塞进了消息体:
但另一半没做:消费端 AccountWaybillFreightPayMQListener 和 AccountPaymentServiceImpl 里完全没有读这个字段——既没还原进 MDC,也没落库。带过去了,没人接。
同一个 trace id,下单的日志全都搜得到,支付的却搜不到。为什么?
现在就在鼎流后台走一遍
-
抓一个真的 trace id
打开鼎流后台任意列表页,F12 → Network,点任意一个接口请求 → 看 Response Headers,找
Trace-Id。抄下这个值。 -
拿它反查
进「监控 → 日志」,在「链路id」列搜刚抄下的值。看能捞出几条、分别来自哪个服务——这就是这次请求真实走过的路。
-
检查探针是否健康
看任意一条日志行开头的
[…]:里面是一串真值,还是TID: N/A?如果是后者,SkyWalking 探针没在工作,先解决这个再谈排障。 -
验证「断链」是真的
找一笔走过运费支付的单,用它的 trace id 搜。观察日志到哪一步停住——停在发 MQ 那一刻,就印证了陷阱二。
主源(推荐今天读):Logback 官方手册 · Mapped Diagnostic Context。整页很短,读完你就彻底明白 %X{tid} 和「按线程」这两件事,两个陷阱都会变成显然的推论。
想再深一层:W3C Trace Context(2021-11-23 正式推荐标准)定义了 trace id 的行业标准形态——「用于在系统中唯一标识一次分布式追踪」。看它能理解为什么各家都在请求头里传这个值。
哪一步的结果和课程不一样,或者你想让我拿一个真实 trace id 陪你走一遍全链路,说一声。陷阱二那个断链是个真缺陷,要不要我整理成方案卡给研发,也随时说。