当 Agent 在第 12 步失败，只保存最后一句“抱歉，任务未完成”几乎没有排障价值。你需要知道：哪次模型请求开始偏离、调用了什么工具、审批是否通过、输出是否被截断、会话能否从持久状态重建。
DeepSeek Harness 的 Session 采用追加式事件日志思路。对可观测系统来说，这比只记录聊天消息更有价值。
Turn、Step 和 Tool 是三层
Turn 是一次输入被接纳后直到不再欠工作的一段处理；Step 是一次模型请求以及它触发的工具执行；一个 Turn 可以包含多个 Step。工具调用和结果又是 Step 内的事实。
指标聚合时不要混用：turn_duration 代表用户感知时长，step_duration 反映模型循环，tool_duration 才定位具体外部能力。只看总耗时，无法判断慢在模型、命令还是网络工具。
两类事件，两种用途
agent/request、tools/result 等 Cordis 事件服务于运行中的扩展和拦截；turn/*、step/*、tool/call、tool/result 等是持久 Session 记录。实时告警可监听前者；审计、恢复和离线分析应依赖后者。
Headless --json 输出则是第三种：面向调用方的 NDJSON 投影。它方便 CI 展示，却不是完整日志，而且非最终字符串可能被截断。三者必须在数据模型中明确标记来源。
最小观测字段
每次运行至少保留：run/session/turn/step 标识；版本、Profile、Preset、Provider 和模型；工作区的不可逆脱敏标识；开始与结束时间；工具名和状态；审批结果；错误码；输入输出 Token（如果 Provider 提供）；最终退出状态；独立测试结果。
不要默认保存完整提示词、思考文本、文件内容和工具输出。可观测数据同样可能包含源码、个人信息和密钥。先保存结构化元数据，再按权限和保留期决定正文采样。
四张最有用的图
第一张是成功率按模型、版本、任务类型分组；第二张是 P50/P95 Turn 与工具耗时；第三张是 Token/费用和重试次数；第四张是权限拒绝、人工接管和回滚比例。
如果升级后平均耗时下降但人工接管翻倍，这不是优化。Agent 平台必须把质量、成本、速度和风险放在同一张评估表里。
用事件重建，而不是复制 UI
Session 日志是事实来源，UI 只是投影。实现自定义控制台时，应从稳定投影构建状态，不要抓取页面 DOM，也不要把某个前端组件的展示顺序当成事件顺序。
插件若需要自己的可恢复状态，应定义持久事件或投影水位；只在内存 Map 里累计计数，重启后就无法解释历史会话。
故障定位顺序
先确认 Session 是否创建，再确认输入是否进入 Turn；接着定位模型请求、流式响应和工具执行；最后检查结果是否提交、是否触发继续步骤、是否写入最终状态。取消、重试和被丢弃的 attempt 要与已提交消息区分。
这套顺序能避免把“UI 没显示”误判为“模型没返回”，也能发现模型已经返回但工具或事件提交失败的情况。
最终建议
从一个只记录结构化元数据的观察插件开始，给每个任务建立 session—turn—step—tool 的关联。对敏感正文默认不采集，对大输出保留摘要和可控访问路径。
可观测性的终点不是更多日志，而是能回答三个问题：发生了什么、为什么发生、升级或重跑后是否真的更好。
继续阅读：生产化、版本升级与回归测试清单。指标体系还可参考AI 内容管线可观测性，完整顺序见DeepSeek Harness 专题路线。