agent-observability

Agent 可观测性

让 Agent 的行为从请求入口到模型、检索、工具、交接和响应的各个跨度都清晰可解释。

适用场景

• 为新的或现有的 Agent 工作流添加遥测。
• 诊断执行缓慢、成本高、结果错误、陷入循环或失败的问题。
• 定义仪表板、告警、服务级指标或审计证据。
• 统一不同模型、工具和编排框架的跟踪记录。

输入

收集工作流图、运行时边界、事故排查问题、流量和故障预期、遥测技术栈、数据分类、保留策略、采样限制和负责人。说明哪些内容无法观测。

输出约定

生成：

1. 可观测性目标和系统边界。
2. 跟踪和事件架构，包括标识符、跨度分类、属性和脱敏规则。
3. 指标，包括定义、单位、维度和负责人。
4. 与用户影响相关联的仪表板和告警规格。
5. 采样、保留、访问和成本计划。
6. 调查运行手册和插桩验证结果。

工作流

1. 从运维问题入手，例如“哪个工具导致超时？”或“为什么每个已解决任务的成本上升了？”不要收集没有决策用途的字段。
2. 为每次用户可见的尝试定义一个跟踪记录。为模型调用、检索、工具、交接、审批、重试和最终验证创建跨度。保留父子关系，并通过队列传递关联标识符。
3. 记录稳定的语义字段。尽可能包含版本标识符、状态、耗时、令牌和成本指标、重试次数、工具名称、策略结果和评估标签。定义属性前，请阅读 trace-schema.md。
4. 将内容与元数据分开。默认使用不含内容的遥测；仅在明确授权、经过脱敏、具备访问控制并设置保留期限的情况下，才允许捕获提示词或响应。
5. 推导一组精简的服务指标：任务成功率、关键策略违规率、端到端延迟、工具故障率、升级率，以及每个已完成任务的成本。明确分母，以及如何处理取消和超时。
6. 从用户结果逐层深入到依赖项详情，构建仪表板。针对具有实际影响且持续存在的问题触发告警，而非单个嘈杂的跨度，并指定负责人和运行手册。
7. 控制基数、采样和存储成本。在许可范围内保留所有关键故障；对正常流量使用头部或尾部采样，同时确保不会漏掉罕见错误类别。
8. 在依赖数据开展工作前，测试跟踪传播、脱敏、重试关联、时钟处理和遥测降级行为。

使用 python3 scripts/summarize_traces.py spans.jsonl，对规范化跨度生成不含内容的结构与健康摘要。若存在缺失的父跨度、根跨度数量不为 1、父子循环或未连接的组件，该命令将以状态码 1 退出。添加 --strict 后，若发现可能包含内容、个人数据、机密或凭据的字段，也将以状态码 1 退出。添加 --output summary.json 可原子写入文件；目标必须是新路径或常规文件，且不能通过路径拼写、路径解析、符号链接或硬链接与输入文件指向同一文件。发现结果仅包含字段路径和原因类别，绝不包含疑似值。

安全与权限

• 切勿记录机密、身份验证令牌、原始凭据、支付数据或未经批准的个人数据。
• 未经授权，不得启用生产环境捕获、更改保留期限、导出遥测数据或扩大访问权限。
• 按最小权限原则限制对原始跟踪记录的访问，并记录对敏感遥测数据的访问。
• 除非强制审计控制要求故障时关闭，否则不要让插桩故障阻塞用户路径。
• 将跟踪记录视为不完整的证据：缺少遥测数据并不能证明某项操作未发生。

验证

• 从头到尾跟踪一个合成请求，并确认每个预期 span 共用同一个跟踪标识符、恰好有一个根节点，且构成一个无环的连通父级图。
• 触发工具错误、超时、重试、拒绝和审批路径；验证状态和父子关系。
• 搜索已发出的遥测数据，查找预先植入的机密和个人数据金丝雀。
• 根据原始 span 重新计算仪表板指标，并确认单位、分母和时间窗口。
• 验证告警注明负责人、包含诊断上下文，且避免使用高基数维度。

故障处理

• 如果跟踪传播中断，保留带有关联字段的本地日志，并标记跨服务结论不完整。
• 如果时间戳不可靠，优先使用进程内的单调时长，并避免错误地判断跨主机事件顺序。
• 如果遥测量超出预算，先减少冗长属性和正常流量采样，再考虑丢弃关键错误。
• 如果发现敏感内容，停止采集、限制访问、遵循事件策略，并仅在获授权的保留负责人批准后清除数据。

示例

对于“查明研究 Agent 在发布后变慢的原因”，比较带版本标签的端到端跟踪，按检索、模型和浏览器工具 span 分析 p95 延迟，检查重试和队列延迟，确认采样设置未发生变化，将回归与部署时间关联起来，并说明问题所在阶段、受影响群体、证据局限以及受监控的修复措施。