结构化日志（structured log） 核心概念

它是什么

结构化日志（structured log）指把每个事件盖上有归属、有序次的元数据，再序列化为一行可机器解析的记录（典型是 JSON）。第 20 章的做法是每个协议事件进来时盖两个戳：seq（全局递增序号，跨会话可比较先后）与 ts（墙钟时间，观测层看到该事件的时刻），产出形如 { type, sessionId, seq, ts, ... } 的事件行。与普通 print 日志相比，它的三个差别是决定性的：可检索（按字段过滤而不是正则抠字符串）、可排序（seq 是唯一权威次序）、带归属（sessionId 说明这一行属于哪次会话）。

与 trace 的关系

事件行是聚合出 trace 的「砖」：盖完章的事件按 sessionId 归组、按 seq 排序，就是一次运行的完整记录。所以日志与 trace 不是二选一，而是「行与运行」两层——这也是 OpenTelemetry 三支柱里 logs 与 traces 并存、并自动互相关联的原因。

关键设计：seq/ts 不进协议

盖章副本是观测层自己的视图：转发给 SSE 缓冲的是原始事件，wire 上跑的还是第 15 章定稿的事件，一个字节没改。可观测性是一层包在 onEvent 外面的观察者，不是协议的一部分——把 server 和 cli 删掉，core 照常跑、照常测。

常见坑

• JSON 不等于结构化：光把对象 JSON.stringify 但字段不固定、schema 不稳定，下游依然无法可靠解析（OpenTelemetry 把这种叫 semistructured）；
• 排序键用 ts 不用 seq：同毫秒发出的事件 ts 相同，顺序会「乱」；
• 日志内容不脱敏：密钥脱敏是打日志前的最后一道工序，见第 23 章。