14 · Observability：沿一份慢报告找到错误从哪里进来

可观测性把“报告用了多久”和“这个结论从哪里来”连到同一次执行上，帮助团队找到真正需要调整的环节。

本课的位置：Observability位于图底部并贯穿全部执行，关联模型、工具、等待与消耗，帮助还原这一次发生了什么。

研究Agent接到任务：“比较Fieldbook两版说明，确认v2活动日志保留多久，给出出处。”Fieldbook是本课虚构的产品：v1写30天，v2改为45天。报告草稿却写着“v2保留30天”，用户还等了很久。

这时直接换模型，可能既没有解决等待，也没有解决错误。我们沿这份报告走一遍：任务在哪里排队，模型提出了什么，工具交回了哪版资料，合并时采用了哪个值。下面的资料、事件和时间均为教学情境，用来解释定位方法，不代表某个产品的性能或效果。

观测层位于执行链路旁边。Harness、调度器、模型适配器和工具提供事实，它负责关联与查询；是否允许继续执行，仍归Run控制层。传统后端也用调用链定位请求，Agent还要把每轮资料、提示版本和子任务身份接上，否则只能看到最终回答，看不到错误是从哪一层进入的。

先把“这个任务”与“里面的工作”分开

Trace是一组相关执行的轨迹，Span是其中有起止时间的工作段，Event是段内某个时刻的事实。它们分别帮助回答：这是哪一次调查，时间花在哪一段，那一刻究竟发生了什么。

这份报告有一条主轨迹，包含排队、模型规划、版本说明读取、目录读取和合并五段工作。Session保留持续对话，Run表示本次完整执行；后续重做报告时建立关联的新Run，不覆盖旧轨迹。

同一逻辑操作还可能经历多次尝试。第一次查询超时、第二次成功，应保留两个尝试及共同操作身份，不能把它们拼成一次没有失败的调用。父子Agent关系回答谁委派了任务，执行者身份回答实际由哪个工作进程完成；执行者接管后，两者尤其不能混为一谈。

每段工作在开始时记录归属，结束时记录结果和持续时间；失败也要有收尾。这样既能看到成功路径，也能找到异常发生前已经完成了什么。

这里采用的是OpenTelemetry等观测体系常见的轨迹与工作段概念。持续时间宜使用不受系统校时影响的计时方式；跨机器还要考虑时钟偏移，不能只按所有日志的时间戳排序。

进程突然退出时，结束记录仍可能缺失。缺尾巴只能说明观测不完整，不能证明工作没有发生，更不能据此重新发送通知。开始、结束和异常是观测信息，外部动作是否完成还要查独立的业务记录。

先回答慢：用户等了8秒，哪一段决定完成时间？

假设这次调查留下以下时间线。为便于看依赖，省略很短的调度间隙：

用户等待8秒，子工作持续时间加起来却是10秒，因为两项读取重叠。决定完成时间的关键路径是“排队→模型规划→版本说明→合并”。主Span覆盖全程，不能再把它加进子项总和。

因此，先把目录读取从2秒缩到1秒，报告仍要等版本说明到第7秒才开始合并。要缩短完整报告时间，应先把版本说明这4秒继续拆开：连接等待、缓存查找、远端查询、内容读取，各自占多少？找到慢段只是下一步调查入口，不是已经证明存储或模型有问题。

另一种选择是增加并发或调整队列优先级。它可能减少排队，却增加资源峰值，也可能让其他任务等待更久。若用户主要抱怨看不到进度，可以先展示“已取得目录，正在核对版本说明”；这改善可见性，并没有让完整报告更早完成。

单次定位按Run查轨迹，看一周趋势则汇总各阶段时延与成功、失败、未知分布。只统计成功任务，会把慢到超时的那批藏起来。任务编号适合检索，也不宜成为无限增长的指标标签。

再回答错：30天究竟在哪一步进来的？

先看任务与模型计划，二者都要求v2。再看版本说明工具交回的信息：

这条链把调查范围缩小了：任务要求没有变，错误首次出现在工具返回；合并随后沿用了错误资料。工具正常返回，不代表返回内容符合当前任务。

继续查缓存规则，发现v1结果按产品名保存，v2请求仍使用同一个命中范围。应该修的是资料复用规则。只给提示词加一句“认真核对版本”，会把本应在工具层解决的问题推给每轮模型判断。

修正后，缓存按产品与资料版本区分，v2请求取得45天及v2出处。真实系统还要纳入租户、权限和内容修订；若同一版本会被编辑，只有版本名仍不够，需要不可变修订或内容摘要。

可以选择每次绕过缓存，优点是直接取源资料，代价是更多读取与等待；也可以细化缓存范围，保留复用收益，但必须维护失效和权限；还可以等合并时发现不匹配再回源，能够兜底，却多一次往返，而且更晚才暴露错误。

本情境采用“工具层修复复用规则，加上交付前检查”。草稿的来源版本不符合任务，就先阻止交付；取回正确资料后再继续。发现错误因此不只是留下警告，还会改变结果能否送到用户手里。

如果工具已经返回v2，合并却写30，就继续查合并输入与输出；如果计划本身请求v1，则向前查要求和上下文版本。请求、实际返回与产物已能构成定位证据，不需要保存模型的私有内部思考。

时长、费用和记录完整性，是三件事

8秒不能换算成多少token或多少费用。若最终用量记录缺失，就保留“用量未知、费用待核对”，不能填0。需要保存厂商请求标识、服务报告的输入输出与缓存用量，再结合计价版本估算；估算和实际账单也要区分。

父Agent的消耗若已汇总子Agent，统计时不能再把子项加一次。失败、取消和重试也可能产生费用，不能只看成功报告的最后一次调用。

观测信息本身同样有代价。保存完整输入输出便于追踪，却可能泄露资料、凭据或个人信息；只存函数名又不足以定位版本错误。比较稳妥的默认记录是范围、版本、数量、必要摘要与受控来源引用，原文另设权限，授权头等敏感内容在进入采集系统前移除。

详细轨迹可以采样。开始时选取部分轨迹开销较小，但当时不知道最后会不会出错；结束后按错误或时延保留，更容易留下这类现场，却需要暂存更多事件。筛选后的轨迹不能直接代表全体成功率。

采集队列满或网络异常还会丢事件，因此需要监测丢弃与导出失败。调试日志可以抽样，业务动作、取消待办和对账依据则要可靠保存。没有发送日志，不能解释成没有发送；否则一次观测丢失可能引出重复通知。

回放也要分清目的。只读回放重建当时的时间线、资料版本与动作事实，不重新查工具、不调用模型，也不再次发布。重新执行则是新的工作，要重新核对权限、输入、预算和副作用；即使材料相同，也不能保证模型再次作出相同选择。

这样，一份慢且错的报告就能被拆成两个具体问题：等待沿依赖链定位，错误沿来源链定位。下一课继续讨论，一次看似省查询的优化，应当怎样决定保留还是回退。