结论先行:Agent 系统的可观测性要回答三个问题——这次任务为什么花了这么多 token(trace)、失败的那次到底发生了什么(回放)、Agent 到底对生产环境做了什么操作(审计)。传统 APM 只覆盖服务调用链,看不到 prompt、工具入参和 token 分布,所以 Agent 可观测性的核心是结构化事件日志:每次 LLM 调用和每次工具调用都落一条完整记录,其余的分析能力都建在这上面。

为什么传统 APM 不够

一次 Agent 任务在 APM 里就是一个长 HTTP 会话,span 树只能告诉你"调了 LLM 服务,耗时 90 秒"。但你真正需要的信息全在载荷里:system prompt 是哪一版、模型选了什么工具、工具返回了什么、token 是怎么分布的、哪一步开始跑偏。这决定了 Agent 的可观测性必须自建事件层,APM 只当传输管道。

类比微服务的可观测性金字塔:指标(metrics)在上、日志(logs)在中、链路(traces)在下。Agent 系统里这个金字塔要换材料——“日志"不再是应用日志,而是结构化事件;“指标"不再是 QPS 和 RT,而是 token、成本和任务成功率;“链路"除了服务调用还要串起"模型看到了什么、据此做了什么”。材料换了,方法论没换:先有完整的一手记录,才有可靠的上层聚合。落到团队分工上,事件层的建设责任应该归 harness 团队而不是各个应用——事件结构是平台契约,应用侧只需要在派生子 Agent、自定义工具时遵守注入规范,各自为政的事件格式会让跨任务的聚合分析无从做起。

事件模型:一次调用一条记录

最小可用的事件结构,每个 LLM 调用和工具调用各记一条:

{
  "trace_id": "t-20261017-001",
  "span_id": "s-042",
  "parent_span_id": "s-001",
  "type": "tool_call",
  "agent": "coder",
  "tool": "Edit",
  "input": { "file_path": "/src/service/OrderService.java", "old_string": "...", "new_string": "..." },
  "output": { "ok": true },
  "tokens": { "input": 41200, "output": 580, "cache_read": 21000 },
  "cost_usd": 0.089,
  "duration_ms": 1230,
  "ts": "2026-10-17T14:03:22+08:00"
}

字段设计的三个要点:一是 trace_id 贯穿主 Agent 和所有子 Agent(parent_span_id 串出树形),否则并行子 Agent 的账对不上总任务;二是 input/output 完整落盘(脱敏后),这是回放的原材料;三是 token 和成本挂在每条 span 上,成本归因可以下钻到"哪一步花的钱”。

第二点上有一种常见的错误做法,对比一下:

{
  "trace_id": "t-20261017-002",
  "span_id": "s-043",
  "type": "tool_call",
  "tool": "Read",
  "input": { "file_path": "/src/service/OrderService.java" },
  "output_summary": "读取成功,内容约 1200 行,此处省略",
  "ts": "2026-10-17T14:05:11+08:00"
}

摘要化保存的问题在回放时爆发:你只知道"读了文件”,不知道模型当时看到了什么——而 Agent 失败的根因恰恰常是"它看到的内容有误导性"。摘要可以额外存一份做快速浏览,但完整 input/output 必须是原始记录,两者是补充关系不是替代关系。OpenTelemetry 社区已有 GenAI 相关的语义约定(记录模型、token 用量、调用参数等属性),自建时可以参照它的字段划分,方便日后接标准生态。

trace 贯穿与成本归因

trace_id 的价值在子 Agent 场景下最明显:主 Agent 派出三个并行子 Agent,每个子 Agent 内部几十次 LLM 调用和工具调用,没有统一的 trace 树时,这些消耗在账单上是散落的孤点,归因无从下手。有了树形结构,两个下钻方向都通了:从成本出发,“这个任务为什么贵"可以一路下钻到最贵的那一次工具调用;从故障出发,“这个子 Agent 为什么改错了文件"可以回溯到它当时读到的上下文。harness 侧的实现要点只有一个:派生子 Agent 时把 trace_id 和 parent_span_id 注入它的全部事件,这条纪律要在 harness 层强制,不能靠各子 Agent 自觉。任务说明书的文本本身也值得作为一条事件记录——它决定了子 Agent 的全部行为,回放时没有它,“子 Agent 为什么没做某事"这类问题就答不了。

三层消费:监控、回放、审计

监控层看聚合指标:任务成功率、每任务 token/成本分布、工具调用失败率、上下文压缩触发次数。要按任务形态分组看——探索类任务和编码类任务的成本基线完全不同,混在一起的平均值没有意义。

回放层解决"失败归因”。拿到 trace_id 后按时间线重演全部事件:模型每步看到了什么、基于什么做出了那个决定。90% 的 Agent 失败回放到某一步就能定位——工具返回了误导性内容、关键约束被压缩掉了、某个工具描述有歧义。回放能力的前提是 harness 侧全量记录,所以这事情要在第一天就做,事后补记是补不回来的。

审计层面向合规与安全:Agent 改了哪些文件、执行了哪些命令、调了哪些外部接口,与权限系统的 allow/deny 记录、hook 拦截记录合并成完整操作账本。生产环境里这份账本不是可选品——“AI 动了生产配置"这类事故的第一反应就是查它。

层回答的问题手段产出物
监控系统健康吗,钱花得正常吗聚合指标、分组对比看板与告警
回放那次失败到底发生了什么按 trace_id 重演事件流归因结论与修复项
审计Agent 对环境做了什么事件 + 权限/hook 记录合并完整操作账本

落地清单与脱敏

按优先级:第一步落结构化事件到本地 JSONL(一天工作量,立刻可用);第二步加 trace_id 贯穿和成本聚合(月末账单可解释);第三步做回放工具(哪怕只是个按 trace 过滤的 jq 脚本);第四步接 OTel 供平台级监控。四步之间没有依赖倒置的风险,每一步独立产生价值,做到第二步就能覆盖日常八成的归因需求:

# 最简回放工具:按 trace_id 过滤,按时间线输出关键动作
jq -r 'select(.trace_id=="t-20261017-001") |
       [.ts, .type, (.tool // .model // "-"), (.output.ok // "-")] | @tsv' \
  traces-2026-10-17.jsonl | column -t -s$'\t'

配套两条纪律:敏感信息(密钥、客户数据)在落盘前统一脱敏,事件日志保留期与安全合规对齐。脱敏容易做错的方向是"为了省事只存哈希”——回放需要的是脱敏后的原文结构,不是等值校验;密钥类字段替换占位符即可,客户数据类字段按合规要求打码。事件日志保留期同样有反直觉之处:Agent 系统的 trace 往往比业务日志更有长期价值(它记录的是决策过程),保留策略要单独定,不要照抄应用日志的 7 天。

实战场景

一次典型回放的完整过程:某天一个自动修复任务的 trace 显示成本是平常的十几倍,且最终改动被人工回滚。拿到 trace_id 后按时间线重演:第 6 轮模型读取了一个接口文档文件,该文件是另一个团队两天前改过的旧版,描述的参数结构已变更;模型按旧文档写了适配代码,第 9 轮测试失败后进入自我修复循环,反复在"再读一遍文档"上打转——因为文档内容每轮都被原样塞回上下文,模型始终没意识到文档本身过时了(场景为写实描述,具体轮数与金额从略)。归因结论两条:一是文档源没有版本标注,工具返回里加一行"该文档最后更新于 x 月 x 日"即可让模型警觉;二是自我修复循环缺少轮数上限,harness 补了循环熔断。两条修复都来自回放,全程不到一小时。反向的例子也有:没有事件记录的 Agent 系统,团队只能靠当事人回忆"它当时大概读了什么”,同类的失败反复发生却始终找不到共同根因——这就是有 trace 和没 trace 的差距。

检查清单

  • 每次 LLM 调用与工具调用各落一条结构化事件,JSONL 即可起步
  • trace_id 贯穿主 Agent 与全部子 Agent,parent_span_id 串出树形
  • input/output 完整落盘(脱敏后),不摘要化替代
  • token 与成本挂在每条 span 上,成本可下钻到单次调用
  • 事件里带上 prompt 版本、模型名、工具名等归因必需字段
  • 敏感信息落盘前统一脱敏,保留期单独制定并与合规对齐
  • 有一个最简回放工具(按 trace_id 过滤的时间线输出)
  • 监控指标按任务形态分组,不混用平均值