Trace（轨迹） 核心概念

它是什么

Trace（轨迹/追踪）是一次运行的完整记录：起点、终点、期间每个事件（按序）、累计的资源用量（token）、最终结果。与日志的一行一记不同，trace 回答的是「这一次运行发生了什么、花了多少、成没成」。在 OpenTelemetry 的模型里，trace 由若干 span 组成（span = 一段有起止的工作单元），分布式场景下通过 W3C Trace Context 的 traceparent/tracestate 头在服务间传播 trace-id，把散落在多个进程里的 span 拼回同一条路径。第 20 章把这个模型简化成一轮对话 = 一条 trace（一个 span），不嵌套、不传播——但「记录一次完整运行」的本质一致。

生命周期

trace 由协议事件界定生命周期：

• 该会话的第一个事件打开 trace（起点 = 该事件的 ts）；
• done 事件累计 usage 并关闭 trace，结果记为 ok；
• error 事件关闭 trace，结果记为 fail。

多轮会话（同一 sessionId 多次 POST /chat）产生多条 trace——一条一轮。派生物三件套：token（来自 done.usage）、耗时（起点 → 终点，毫秒）、结果（ok/fail）。

在本教程的位置

两层意义：一是可观测——createTraceRecorder 包在 onEvent 外面，把盖章事件行（structured-log）聚合进 trace，GET /traces 暴露；二是评测——trace 是第 13 章的判题对象：只看最终答案会漏掉「答案对了但行为浪费」的失败运行（多绕了几轮、调了不该调的工具），把 trace 喂给 grader 才能对「过程」评分。失败 trace 还会被归入 error / tool / budget 三桶（第 20 章），回答「先修什么」。

常见坑

• trace 过大：工具输出可能很大，生产要截断大 payload 或给 trace 设体积上限；
• 时间口径：ts 是观测层「看到」事件的时间，事件源头打点（performance.now()）才精确；同毫秒事件按 ts 排序会乱，排序键是 seq；
• 多实例：全局 seq 在多进程部署时要换成 (实例 id, 本地 seq)。