AI Agent 可观测性实战：从 correlationId 到失败时间线

痛点一：日志碎片化。难以追踪完整任务链——Agent 调用链越长，日志越容易陷入反直觉的问题：每个组件都记录了内容，但没有人能还原“这一次任务”到底发生了什么。

痛点二：隐私泄露与存储膨胀——把所有上下文原样塞进日志。会导致敏感信息外泄、存储成本飙升，还有诊断接口失控。

工程上的选择不是继续堆日志。而是身份：用一个 correlationId 串起请求、规划、工具、外部动作和验收，再提供有资源边界的时间线查询。

工程场景与决策冲突

一个多步骤 Agent 可能同时拥有 requestId运行实例 ID、会话 ID、工具调用 ID 和目标对象 ID。它们都有价值，却不能替代端到端任务身份。

如果每一层只记录自己的局部 ID，故障定位只能靠时间猜测；不过，如果把所有上下文原样塞进日志。又会带来隐私泄露、存储膨胀和诊断接口失控。

痛点三：定位效率低下必须依赖模糊时间窗口

我采用三条边界：

1. correlationId 负责串联，不承载秘密；
2. 结构化事件记录工程事实不保存完整敏感内容；
3. 时间线查询必须有 limit、时间、扫描字节和游标边界。

方案拆解与关键权衡

一条最小执行链可以表示为：

Request -> Plan -> Tool -> Action -> Verify -> Outcome

每个节点共享 correlationId但保留自己的局部 ID。这样既能端到端串联，也能在具体组件中继续下钻。

事件字段控制在可比较范围内：

event = {
再看"ts"，now_iso,"event": "tool.failed","outcome": "failed","correlationId": cid,"requestId": request_id。"reasonCode": "navigation_timeout","target": {"tool": "browser","tabId": safe_tab_id},}

痛点四：自由文本难以统计与自动恢复——这里的 reasonCode 比自由文本更适合统计和自动恢复；老实说，自由文本只作为脱敏补充。

实现链路与最小示例

入口只生成一次

def start_context -> dict:
cid = validate_id or new_uuid
return {"correlation_id": cid}

上下文应显式向下传递。线程本地变量或隐式全局状态虽然方便，但跨异步任务和进程时更容易断链。

每个副作用动作成对记录

record
从try来看，result = execute
except Exception as exc:
record)
raise
再看else，record

查询失败时间线，而不是全文搜索

timeline = diagnostics.query(
correlation_id=cid。mode="failures",since=incident_start,until=incident_end,limit=100,cursor=cursor,)

生产实现还应限制 max_scan_bytes 和 timeout_ms. 如果查询被截断，就返回 nextCursor 与明确原因，调用方再决定是否续读。

证据、限制与自动化边界

真实实现中的诊断器支持按关联标识、请求标识、事件、相关对象和时间窗口过滤；失败模式只选择 "failed","degraded"。"dropped"

痛点五：敏感信息泄露风险 - 这些证据并不代表着可以记录模型完整推理。更安全的边界是记录输入输出哈希、工具名、参数的安全摘要、令牌数量、延迟、结果和来源，不保存 Cookie、授权令牌和不必要的个人信息。

自动恢复也不能只看 "failed". 如果外部写动作超时结果可能未知；恢复器必须先回读业务事实再判断是同步状态、继续验收还是使用幂等键重试。

可复用检查清单

• 端到端任务是否只有一个统一的关联标识？
• 局部 ID 是否保留，且能映射到关联标识？
• 事件名、结果和原因码是否受控？话说回来，
• 是否避免记录敏感正文和令牌？不过，
• 是否记录动作开始与结果？怎么说呢，
• 时间线查询是否有数量、时间和字节预算？说起来，
• 截断是否可用游标稳定续读？
• 外部写操作恢复前是否先回读事实？
• 是否有失败筛选、分页和损坏记录测试？

收束

价值不是让日志网站更热闹，而是让一次任务的事实链可以重建、解释和安全恢复。

Your Agent 最缺的是统一关联 ID，还是工具调用的结果契约？先回答这两个主要痛点，再逐步落地上述边界。你就能把“看不见的错误”变成“可追溯的事实”。

发布前门禁

• 减少重复背景
• 突出工程选择而非概念堆砌
• 不给未经验证的数据结论
• 本轮无已认领实验，不自行补写实验结论