Agent 上线几周后，最常见的一类追问是：“它当时为什么做了那个动作？” 如果你的日志只记了最终输出，这个问题答不上来——系统看起来只是“偶发出错”，但你无法还原它的决策过程。
可观测性不是上线后再补的锦上添花，而是排障、审计和成本治理的地基。这篇讲一次工具调用到底该记哪些字段，以及怎么把它们串成可还原的一次运行。
一、一次工具调用的最小字段集
围绕“事后能不能还原这次决策”来定字段，至少要有下面这 8 类：
- 工具名与版本
- 入参（结构化）
- 出参或错误
- trace id / run id
- 错误码与错误分类
- 重试次数
- 权限上下文（谁、什么角色）
- 耗时
只记输入输出是不够的——中间的重试、降级、权限判断，都是排障时要看的。
二、用 span 把一次 run 串起来
一次用户请求可能触发多次工具调用、多轮模型交互。用 trace / span 把它们串在同一个 run id 下，才能看到完整链路，而不是一堆孤立日志。OpenTelemetry 是通用做法：
const span = tracer.startSpan("tool.call", {
attributes: {
"run.id": ctx.runId,
"tool.name": name,
"tool.retry": ctx.retry,
"actor.role": ctx.role,
},
});
try {
const out = await dispatch(name, args);
span.setAttribute("tool.status", "ok");
return out;
} catch (e) {
span.setAttribute("tool.status", "error");
span.setAttribute("tool.error_code", e.code);
throw e;
} finally {
span.end();
}
三、成本与延迟也要进指标
Agent 的成本和延迟同样要可观测：每次模型调用的 token 数、每个工具的耗时、一次 run 的总成本。否则成本异常和体验劣化都只能靠“感觉变慢了/变贵了”来发现，而不是靠数据定位到哪个环节。
四、几周后还能不能还原一次决策
判断可观测性做得够不够，有个简单标准：几周之后，能不能只靠日志完整还原某一次具体决策？ 如果只能部分还原，说明关键字段缺失。事故复盘或审计追问“它为什么这么做”时，系统必须给得出答案。
日志量担心可以用结构化 + 采样解决，但关键动作（尤其有副作用的写操作）应全量记录，不采样。
常见问答
Q：只记输入输出够吗？ A：不够。要能逐步还原：中间的重试、降级、权限判断都得在。只记首尾等于放弃了中间决策的可追溯性。
Q：日志会不会太多、太贵？ A：结构化 + 对低价值链路采样；关键/高风险动作全量。用 span 聚合后，存储和查询都比一堆散日志高效。
Q：可观测性和审计是一回事吗？ A：高度重叠但侧重不同：可观测性偏排障与性能，审计偏“谁做了什么、可追溯合规”。字段设计上可以共用一套底座。
一次工具调用记全字段、用 span 串起一次 run、把成本延迟也纳入指标——这三件事决定了出事时你能不能查清。这正是生产就绪审查里“可观测与审计”支柱要逐项对照的内容。
小结：一次调用记全字段、用 span 串起一次 run、成本延迟进指标（span 属性命名可参考 OpenTelemetry 官方文档的约定）。想按这些字段自查现有系统能不能还原一次决策，可以做一次生产就绪自检。