Java转AI Agent教程(第十八周)Trace 与脱敏(trace_id 贯穿 + JSONL 回放 + PII 脱敏)

Source

W18 · Trace 与脱敏(trace_id 贯穿 + JSONL 回放 + PII 脱敏)

本周验收:一个 trace_id 能回放并定位到 prompt 版本;日志里搜不到任何真实手机号。
全部断言见 bash run.sh drill w18(24 条)。

一、这周解决什么问题

上线后第一封用户投诉邮件来了,你说「我查一下日志」,然后看到的是滚屏的字。
trace 的价值不是「有个 id」,而是凭这个 id 能回答三个问题:

  1. 这次请求走了哪些步骤?(每步到什么状态、耗时多少)
  2. 每步用了哪个版本的 prompt?(改过 prompt 之后,这条回复是哪版生成的)
  3. 花了多少 token 和钱?

三个问题答不上来,那不是可观测性,是日志。

二、脱敏:靠结构,不靠自觉

obs/Pii 六类规则,顺序有讲究(先打强特征,最后兜底长数字):

类型 规则 例子
手机号 3+4+4 分组,容忍 -/空格 138****5678(保留前 3 后 4,排障要回电线索)
邮箱 整体替换 ***@***
身份证 留头 4 尾 2 中间 11 位打码
详细地址 只留省市 客服排障只需要「哪个城市」,不需要「哪栋楼」
收件人 留姓 王**
银行卡 13–19 位兜底,留尾 4 在前面规则之后扫,避免重复匹配

两条设计原则:

  • 脱敏放在组装层(TraceStore.build),不是落盘层。组装层的输入已结构化,
    落盘层再补就来不及了——中间任何一处 System.out 都可能已经泄了。
  • 宁多误伤、不可漏放。11 位数字不一定是手机号,但漏放一条的代价远大于
    多打码一串。反过来的红线也有:订单号、金额不脱敏——过度脱敏的日志
    没法排障,等于没做。

三、JSONL:为什么不是数据库

每行一个 JSON 的追加写,grep / jq 直接消费;本地工程零存储依赖。
生产换任何 APM/列存,Trace 字段结构不变,迁移成本才低。
TraceStore.replay(jsonl, traceId) 按行扫描找回——30 条数据不需要索引,
需要的是「字段平铺」:排查的人不该为了看一个 token 数钻三层嵌套。

四、实测数字与复跑命令

bash run.sh drill w18    # 24 条断言
验收项 结果
traceId 生成 tr- 前缀 + 时间戳(36 进制)+ 4 位随机,非空、每次不同
凭 id 回答三问 spans 覆盖五步链 / prompt 版本与 FlowResult 逐条一致 / tokens+cost 在 trace 里
引用条款进 trace 可核查性跟着证据走(W16 的 CitationBinding 产出直通)
PII trace 与每步 note 全部过 mask;整个 JSONL 文件 grep 搜不到原始手机号
回放 写 3 行 → 凭 traceId 回放 → 内容一致 → 回放结果同样无手机号

五、防误解的诚实说明

  • 正则脱敏防的是落盘泄漏,防不了模型回复里「复述」用户手机号被发送出去
    (那要靠回复校验层);两者是不同防线,别混为一谈。
  • JSONL 全量扫描式回放在万条以下够用;量级上去后要换带索引的存储——
    字段结构不变,这正是选 JSONL 的原因。

六、本周踩的坑

  1. 手机号正则写成 1[3-9]\d{9} 会把 10 位数字也吞进来(无边界断言时
    订单号的数字段被误伤,且更危险的是短一位的串漏放)。改成 3+4+4 分组 +
    前后不贴数字
    :(?<![0-9])(1[3-9]\d)[- ]?(\d{4})[- ]?(\d{4})(?![0-9])——
    分组正则天然要求 11 位,少一位吞不出来。
  2. 断言「搜不到原串」必须连回放结果一起查:写进去的时候干净不算数,
    读出来再序列化一遍还是要干净的——JSON 转义可能把原串搬回来。
  3. 手机号保留了前 3 后 4 有人质疑「算脱敏吗」:算。日志的用途是排障,
    排障需要回电线索;全打码的日志等于让人放弃排障。要区分
    「日志脱敏」和「对外展示脱敏」——后者才是全打码。