AI agent 可观测性应能还原一条运行从用户请求、模型调用、工具选择、策略决策、工具执行、下游影响、重试直至最终响应的完整过程。日志、指标、链路追踪和评估分别回答不同问题，只收集模型文本远远不够。
先选择一条失败或成本异常的工作流，再检查是否有一个标识符能贯穿到权威后端结果。
追踪完整决策与执行路径
sequenceDiagram
participant U as User
participant A as Agent
participant M as Model
participant P as Policy
participant T as Tool
participant B as Backend
U->>A: Request
A->>M: Model call
M-->>A: Tool selection
A->>P: Authorize identity and action
P-->>A: Decision
A->>T: Tool call with operation ID
T->>B: Downstream request
B-->>T: Authoritative result
T-->>A: Structured result
A-->>U: Response
使用一条 trace 记录整次运行，用 span 记录模型和工具工作，并为可能比 trace 存活更久的外部影响分配操作 ID。条件允许时，将工具调用 ID 传入服务端。数据库行应能反向关联操作和 trace，但无需保存完整 trace。
OpenTelemetry 发布了适用于模型、agent 和工具 span 的 GenAI 语义约定。这些约定仍在演进，应固定所用版本，并维护一层精简的内部 schema，不要让实验性属性名称散落在整个应用中。
捕获能够解释运行过程的事实
模型 span
记录提供商、模型、响应标识符、延迟、token 用量、结束原因、重试次数和提示词模板版本。只有策略允许时才保存完整提示词；普通 trace 中使用 hash、脱敏样本或受保护引用可能已经足够。
工具 span
记录模型可见的工具名称和版本、工具调用 ID、脱敏参数、选择来源、持续时间、结果类别、重试次数和下游操作 ID。明确区分“模型选择工具”“策略允许工具”和“后端完成操作”。
策略与审批 span
记录所代表的身份、租户、资源、操作、策略版本、决策、原因码和审批引用。绝不能记录 access token 或原始密钥。请求被拒绝是预期的策略结果，不一定属于应用错误。
恢复 span
将恢复后的工作与原始工作流和操作关联。记录系统是进行了重试、核对未知结果、补偿已完成操作，还是停止等待人工审核。故障恢复指南介绍了这些分支。
使用指标观察趋势，而不是解释单次运行
聚合指标应包括：
- 成功、失败、拒绝和取消的运行数；
- 任务完成率和人工升级率；
- 按百分位统计的模型与工具延迟；
- 每项任务和每个租户的 token 与提供商成本；
- 工具选择、校验、授权和后端错误率；
- 重试、重复调用、循环停止和未知结果；
- 队列延迟、活跃运行数和检查点时长。
不要使用提示词文本、用户 ID、工具参数或 trace ID 等无界值作为 label。应将这些值放入受保护的日志或 trace，并保持指标维度有界。
将日志保存为离散且已脱敏的事件
日志适合记录部署变更、策略决策、操作状态转换、提供商错误和清理。使用稳定的事件名称与结构化字段，不要在每一层重复记录完整模型 payload。
数据离开进程前就应完成脱敏。提示词和错误中可能包含密钥、Authorization header、个人数据、检索文档和工具输出。导出后再采样无法撤回已经泄露的数据。
使用评估衡量质量
遥测能说明发生了什么，但如果没有预期行为，它无法判断响应是否有帮助或工具选择是否正确。将生产故障和抽样 trace 加入有版本记录的评估集，再在更改模型、提示词或工具契约前运行。
AI agent 评估指南分别介绍了确定性断言、模型判定、重复试验和发布门禁。
围绕可执行操作设置告警
只对有明确处置方式的情况发出告警，例如部署后大范围授权失败、破坏性工具调用激增、trace 连续性缺失、反复出现未知结果、队列积压、触及费用限制，以及运行超出调用次数或时间预算。
不要为每次模型错误都触发值班告警。先按提供商、模型、工具、版本和结果类别分组。看板可以展示有噪声的质量变化，值班告警则应对应具体的隔离或回滚操作。
添加看板前先审计一条 trace
手动追踪一次真实运行。能否确定提示词版本、工具列表、策略决策、下游请求、业务结果、成本和所有重试？能否从 trace 找到受影响的操作，也能从操作反查 trace？
下方的提示词会在不传输数据的情况下，对当前仓库执行这项审计。首个缺失的关联，比再增加一张聚合图表更应该优先修复。