←AI 实践笔记
Lesson 0005 · 约 9 分钟

一次请求的
身份证

前四课都在读静态的代码——文件、分支、冲突。这一课换一头:代码跑起来之后留下的痕迹。学会用 trace id,你就能从「用户说支付失败了」直接跳到「是 vcm-user 这一行报的错」,不用翻七个服务的日志。

先看东西在哪:一次请求走三站

trace id 不是一个存在某处的字段,而是同一个值在一路上反复留下的痕迹。你要建立的是这张位置图——哪站留了痕、留在哪、你从哪伸手去拿:

第 1 站 · 你的抓取入口

浏览器 / 货主端 App

请求发出去,响应回来。响应头里带着这次请求的 trace id——这是你唯一不用登服务器就能拿到它的地方。

F12 → Network → Response Headers Trace-Id

常量定义在 AuthProvider.TRACE_ID,值就是字符串 "Trace-Id"。

第 2 站 · 刻意不留痕

vcm-gateway 网关

trace id 在这里被生成或被接管,然后塞进请求头。但网关故意不把它放进自己的日志上下文——源码里那行是注释掉的,注释写明「网关不在 ThreadLocal 上下文添加 traceId,用于优化性能」。

网关自己的日志行 %X{traceId:-traceId}

因为没放进上下文,这里打出来的是兜底占位字符串,不是真值。看到网关日志里写着字面量 traceId,那是正常的,不是坏了。

第 3 站 · 痕迹真正落地

业务服务 vcm-order / vcm-user / …

这里才是你查日志时真正能搜到东西的地方。同一个 trace id 会落在三处:

日志文件每一行 [%X{tid}]

SkyWalking 官方 MDC toolkit 打的。每一行都带,所以搜它比搜订单号命中率高得多。

数据库 vcm_user_optlog.trace_id

操作日志落库时用 LogTraceUtil.getTraceId() 取值写进去。

MQ 消息体 AccountFreightPayDTO.traceId

生产端手工塞进去了,但消费端没读——详见下面「陷阱二」。

查看入口:鼎流后台「监控 → 日志」下的几个页面(错误日志 / 常规日志 / 接口日志),都有一列中文标签叫 「链路id」。那一列就是 trace id——名字不一样,东西是同一个。

Retrieval Practice · 1 / 2

用户报障,你要抓这次请求的 trace id。在浏览器 F12 里看哪个?

为什么它能打进日志:MDC

日志行里那个 %X{tid} 不是魔法。MDC(Mapped Diagnostic Context)是 logback 的机制,官方定义是一种「为每一条日志请求盖上唯一戳记」的技术:把上下文信息放进 MDC,logback 就能自动带进每一行日志。

%X 就是从 MDC 里取值的占位符,%X{tid} = 取 MDC 里 key 为 tid 的那个值。

见 Logback 官方手册 · Mapped Diagnostic Context

要记这一句 logback 官方原文:「MDC 按线程管理上下文信息」(The MDC manages contextual information on a per thread basis)。按线程——这四个字是下面两个陷阱的总根源。

诊断信号:看到什么,说明什么

排障时你会撞见这几种情况。能一眼判断它是「真问题」还是「正常现象」,就省掉大半冤枉路:

你看到的
意思
下一步
响应头有 Trace-Id
一切正常
抄下来,去日志中心搜
日志里是 [TID: N/A]
SkyWalking 探针没生效,这次请求根本没被追踪
别怀疑业务代码,先查 agent 挂载
网关日志里是字面量 traceId
正常。网关刻意不落 MDC
去下游服务的日志看真值
前半段搜得到,支付段断了
跨到异步线程,上下文没还原
换业务键(结算 id / 运单号)接着查

TID: 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 手工塞进了消息体:

accountFreightPay.setTraceId(LogTraceUtil.getTraceId()); // FreightSettleServiceImpl

但另一半没做:消费端 AccountWaybillFreightPayMQListener 和 AccountPaymentServiceImpl 里完全没有读这个字段——既没还原进 MDC,也没落库。带过去了,没人接。

对你的影响 凡是走 MQ 的异步动作(运费支付是典型),trace id 只能查到「发消息」那一刻为止。后面的账户扣款、支付回调都搜不到。这就是支付类问题比下单类问题难查的结构性原因——不是你不会查。
Retrieval Practice · 2 / 2

同一个 trace id,下单的日志全都搜得到,支付的却搜不到。为什么?

现在就在鼎流后台走一遍

  1. 抓一个真的 trace id

    打开鼎流后台任意列表页,F12 → Network,点任意一个接口请求 → 看 Response Headers,找 Trace-Id。抄下这个值。

  2. 拿它反查

    进「监控 → 日志」,在「链路id」列搜刚抄下的值。看能捞出几条、分别来自哪个服务——这就是这次请求真实走过的路。

  3. 检查探针是否健康

    看任意一条日志行开头的 […]:里面是一串真值,还是 TID: N/A?如果是后者,SkyWalking 探针没在工作,先解决这个再谈排障。

  4. 验证「断链」是真的

    找一笔走过运费支付的单,用它的 trace id 搜。观察日志到哪一步停住——停在发 MQ 那一刻,就印证了陷阱二。

主源(推荐今天读):Logback 官方手册 · Mapped Diagnostic Context。整页很短,读完你就彻底明白 %X{tid} 和「按线程」这两件事,两个陷阱都会变成显然的推论。

想再深一层:W3C Trace Context(2021-11-23 正式推荐标准)定义了 trace id 的行业标准形态——「用于在系统中唯一标识一次分布式追踪」。看它能理解为什么各家都在请求头里传这个值。

哪一步的结果和课程不一样,或者你想让我拿一个真实 trace id 陪你走一遍全链路,说一声。陷阱二那个断链是个真缺陷,要不要我整理成方案卡给研发,也随时说。

← 上一课:你电脑里有两个 pre · trace id 排障速查 · 调用链速查