跨系统链路追踪
X17：一个 traceId 贯穿 ERP / WMS / TMS / OMS，把"单据卡在哪一跳"从经验判断变成可检索证据。断链定位有三条路径：按 traceId 检索、按单据号反查、按状态机卡点巡检。
今日链路
1,284条
平均 span 数 7.2 · 单链路最长 33.0 秒
单据链路成功率
99.74%
近 30 日 5,412 条，断链 14 条
当前断链
3条
签收回执 2 · 运单回传 1
断链定位时长
6分钟
改造前人工排查均值 45 分钟
采样率
20 / 100%
常态 20% · 告警链路 100% 全采样
链路日志留存
30天
审计类操作日志 3 年（见 mon-log）
链路检索
X17 · 检索即定位| 检索路径 | 适用场景 |
|---|---|
| 按 traceId | 已知链路标识（告警、日志、工单里带出） |
| 按单据号反查 | 只有业务单据号，通过业务键映射到 traceId |
| 按状态机卡点 | 不知道单号，按"超 SLA 未推进"批量捞出 |
链路调用链 · tr-20251018-023108-4c7e9b21
端到端 32.98 秒 · 同步 span 合计 3,932 ms复制 traceId导出链路
02:31:08.004 · OMS 单证服务
创建调拨单 TR20251018-014，1,240 ms，成功（businessKey = OMS:TR20251018-014）
02:31:09.244 · 智能调补 outbox
决策单据落库并写 outbox 表，12 ms；幂等键 = batchId + 行号
02:31:09.256 · ERP 单据中心
回写 wms_doc_header，340 ms；按 docNo upsert（重试无损）
02:31:15.100 · WMS 拣货
生成拣货单 WH01-PK-20251018-0031，1,860 ms（含 5.8 秒排队）
02:31:40.500 · TMS 运单
创建运单 TMS-20251018-77120，480 ms
02:31:41.100 · WMS 拣货作业
波次拣货完成 12 件 / 4 SKU，作业耗时 23.5 秒（人工等待）
02:32:10.880 · TMS 揽收
揽收扫描成功，链路端到端 32.98 秒，单据状态推进到「运输中」
2025-10-20 18:40 · TMS → OMS 断链
TMS 已送达网点，但门店签收回执（POD）未回传 OMS —— 单据状态停留「运输中」，链路在此断开
2025-10-21 09:12 · 巡检任务
单据状态 7 天未推进，自动生成告警 AL-EX-1014 并关联本 traceId
Span 明细（耗时 · 状态 · 上下游系统 · 幂等键）
同步耗时合计 3,932 ms = 1,240 + 12 + 340 + 1,860 + 480| # | 系统 | 服务 / 操作 | 开始时刻 | 耗时 | 状态 | 关键属性（幂等键 / 单号） |
|---|---|---|---|---|---|---|
| 1 | OMS | order-center · POST /transfer/create | 02:31:08.004 | 1,240 ms | 成功 | businessKey = OMS:TR20251018-014 |
| 2 | 智能调补 | trace-outbox · 决策单据 outbox 落库 | 02:31:09.244 | 12 ms | 成功 | batchId + 行号（幂等） |
| 3 | ERP | erp-gateway · POST /doc/upsert | 02:31:09.256 | 340 ms | 成功 | upsert by docNo（重试安全） |
| 4 | WMS | wms-picking · 拣货单生成 | 02:31:15.100 | 1,860 ms | 成功 | pickingNo = WH01-PK-20251018-0031 |
| 5 | TMS | tms-waybill · 运单创建 | 02:31:40.500 | 480 ms | 成功 | waybillNo = TMS-20251018-77120 |
| 6 | WMS | wms-picking · 波次拣货作业（人工） | 02:31:41.100 | 23,540 ms | 成功 | 12 件 / 4 SKU / 作业员 A012 |
| 7 | TMS | tms-scan · 揽收扫描 | 02:32:10.880 | 220 ms | 成功 | 揽收网点 杭州中转场 |
| 8 | TMS → OMS | POD 签收回执（门店签收 → OMS） | 2025-10-20 18:40 | 未回传 | 断链 | 应为 waybillNo + 签收时间 + 签收人 |
共 8 行每页
断链定位方法
- ① 按 traceId 检索
- 日志、告警、工单均携带 traceId，一键出全链路视图，缺失的 span 即断点
- ② 按单据号反查
- ERP 单号 / WMS 拣货单 / TMS 运单号 → 通过业务键索引映射到 traceId
- ③ 状态机卡点巡检
- 单据状态超 SLA 未推进即自动抓链路（本例 7 天未推进，SLA 为 48 小时）
- ④ 下游数量对账
- 按 traceId 汇总上下游数量/金额，差异即断链证据
- traceId 透传
- HTTP header X-Trace-Id / MQ 消息头 / outbox 记录三处强制透传
- 关联字段
- traceId + businessKey + 幂等键 + batchId，四字段可互相反查
链路卫生三条硬要求
① 外部系统必须接受并回传 traceId，否则在集成层补写网关日志；② 出站调用必须携带幂等键，重试才不留脏数据（X13）；③ 采样策略按告警优先 —— 常态 20%，凡产生告警的单据链路必须 100% 全采样，否则事后无法复盘。
断链卡点分布（近 30 日 14 条）
按卡点聚合，才知道该修哪一跳| 卡点 | 平均停留 | owner | Runbook |
|---|---|---|---|
| 签收回执 | 5 天 4 小时 | 周工 · 物流组 | RB-06 |
| 运单回传 | 3 小时 12 分 | 赵工 · 集成组 | RB-07 |
| ERP 回写 | 重试即恢复 | 孙工 · 单据组 | RB-05 |
典型断链案例
断链不是"网络问题"，多数是回传责任没定义清楚| 案例 | 链路 | 影响 | 现象与证据 | 处置与根治 |
|---|---|---|---|---|
| 门店签收回执缺失（本页案例） | TMS → OMS | 断链 7 天 | TMS 显示 10-20 18:40 已送达网点，门店实际已收货但未在门店端确认；OMS 单据状态停留「运输中」，达成率少计 12 件、结算延迟 7 天 | 门店端补录 POD（E8）→ 回执回传幂等入库 → 巡检任务自动关闭；同时给门店端加"48 小时未确认"提醒（AL-06） |
| ERP 回写超时后重试 | 智能调补 → ERP | 无损（幂等拦截） | 首次 POST /doc/upsert 超时（340 ms 阈值 500 ms 但网关抖动），重试第 2 次成功；第 1 次实际已落库，被 docNo 唯一键拦截 | 无需人工介入；保留两次 span 作为"重试无损"证据（X13 幂等边界） |
| WMS 拣货单生成失败 | 智能调补 → WMS | 重试 2 次共 +8 秒 | 库存锁定冲突（同一 SKU 被另一波次锁定），第 1、2 次返回 LOCK_CONFLICT | 退避重试 + 冲突 SKU 分波处理；链路标记 degrade，事后核对拣货数量一致 |
| TMS 运单号未回传门店 | TMS → 门店端 | 降级可用 | 运单创建成功但回传超时，门店端看不到物流轨迹，客服咨询量上升 | 降级使用 ERP 出库单号查询；链路补一次异步回传（MQ 重投） |
共 4 行每页
i设计说明：链路追踪的价值不在"画得漂亮"，而在于把责任边界画出来 —— 每一跳谁负责、承诺多久回传、超时谁升级。本页每条断链案例都直接指向一个 runbook 与一个 owner，否则追踪只是一张好看的图。