AI Agent 生产可观测性清单：trace ID、完整消息上下文、token 成本和脱敏边界怎么配

AI Agent 排错的关键是还原模型当时看到的上下文，并用 trace 把模型、工具和检索串起来。

1. 01先读摘要，判断是否与你的场景相关。
2. 02再看来源，保留继续查证的路径。
3. 03最后看步骤、风险和可复用动作。

AI Agent 比普通 API 难排查的地方在于同一个问题可能走不同工具、读不同上下文、产生不同成本。只记录用户问题和最终回答，等于把失败原因留在黑箱里。这份清单用 OpenTelemetry 的 trace 和 log 思路组织，帮助你上线前就确定要记录哪些字段、怎么脱敏、怎么告警。

适用场景

• 你在生产环境运行会调用模型、工具和外部 API 的 Agent。
• 你已经遇到“模型答错但不知道哪一步错”的情况。
• 你需要按用户、项目或工具维度追踪 token 和费用。
• 团队有日志或监控基础设施，想用同一套 trace 标准接入 AI 工作流。

不适用场景

• 你只跑一次性实验脚本，不需要长期留存和告警。
• 你还没有权限把敏感日志接入 SIEM 或 tracing 平台。
• Agent 调用量极小，记录完整消息历史的存储成本不值得。
• 你希望记录原始 token 和密钥而不做任何脱敏。

准备材料

• Agent 代码仓库和当前模型调用点清单。
• OpenTelemetry SDK 或兼容的 tracing exporter。
• 可查询结构化日志的平台，以及能渲染 span 树的工具。
• 数据脱敏规则和保留周期。

步骤一：先定义 trace ID 和 span 边界

OpenTelemetry 把一次分布式请求拆成 trace，把每个子步骤拆成 span。Agent 里的一次完整运行可以是一个 root span，模型调用、工具调用、检索和写入分别是子 span。跨系统传递同一个 trace ID，才能把失败链路串起来。

1. 在 Agent 入口生成或接收 trace ID。
2. 为模型调用、工具调用和外部请求分别创建 span。
3. 给每个 span 记录开始时间、结束时间、状态和错误。
4. 把 trace ID 放进日志、响应头和外部回调，方便回查。

步骤二：记录结构化日志而不是 print

OpenTelemetry 把 logs、traces 和 metrics 分开，但生产排查时通常要一起看。结构化日志至少包含时间戳、trace_id、span_id、level、agent_id、step 和 event。不要用 print(response)，否则无法按字段过滤。

{
  "timestamp": "2026-08-17T09:00:00Z",
  "trace_id": "abc123",
  "span_id": "model-1",
  "level": "info",
  "event": "model_call",
  "agent_id": "support-agent",
  "model": "gpt-5.6-sol",
  "step": 2,
  "tokens_in": 1820,
  "tokens_out": 240,
  "latency_ms": 1430,
  "status": "ok"
}

步骤三：记录模型输入输出和工具结果

很多 Agent 问题出在上下文：旧记忆被注入、工具返回了错误字符串但模型当成数据、系统提示被截断。调试时最重要的是还原模型当时看到的消息数组。可以记录完整消息历史、工具返回结果和检索片段，但先确认哪些字段需要脱敏。

• 记录模型看到的 messages，而不是只记用户 prompt。
• 记录工具参数、返回值和异常，方便区分调用失败与结果被误读。
• 记录检索到的文档 ID、分数和文本片段。
• 把 token 数、成本和延迟挂到对应 span。

步骤四：对日志做脱敏和保留

Agent 日志是隐私面。完整消息历史可能包含 PII、内部数据和 secret。上线前定义哪些字段只记 hash、哪些字段不落盘、哪些字段在 UI 中打码。OpenTelemetry 的 span processor 可以在导出前修改属性。

1. 扫描示例数据，找出邮箱、电话、地址、API key 和内部 token。
2. 对敏感字段做 redact、hash 或省略。
3. 设置日志和 trace 保留周期，避免无限存储。
4. 确认 tracing 平台的数据驻留位置符合合规要求。
5. 定期用测试数据检查导出内容不包含明文密钥。

步骤五：加错误、循环和成本告警

有 trace 后，才能定义有意义的告警。常见的信号包括模型调用失败、工具连续重试、同一工具参数重复出现、单次运行步骤数超过阈值、token 成本突增。

• 对模型和工具错误设置告警，并带 trace_id。
• 检测相同工具+相同参数连续调用超过 N 次的循环。
• 按 agent、用户或项目统计 token 和费用。
• 把 trace 链接放进告警通知，缩短响应时间。

步骤六：验收一个真实调试流程

配置完成后，用一个已知失败场景走一遍：打开 trace，找到最后正常 span，检查下一步完整输入，再看工具返回值，对比 token 变化。这个流程应该能在几分钟内定位，而不是重新跑日志。

1. 从错误消息或用户 ID 找到 trace。
2. 展开 trace 树，定位失败或异常 span。
3. 查看该 span 的完整输入和工具输出。
4. 检查上下文是否被污染，或步骤是否循环。
5. 修复后对比优化前后的 token 和步骤数。

可复制字段清单

trace_id：
span_id：
agent_id：
user_id：
step：
event：model_call / tool_call / retrieval / error
model：
messages_available：true / false
tool_name：
tool_args：
tool_result：
tokens_in：
tokens_out：
latency_ms：
cost_estimate：
status：
redacted_fields：

实际例子：客服 Agent 从黑箱到可回放

一个客服 Agent 偶尔把订单状态答错。团队原先只记录用户问题和最终回复，无法知道是数据库工具返回了空值，还是模型把旧缓存当成最新状态。接入 OpenTelemetry 后，每次运行都有一个 trace，模型调用、订单查询和知识库检索分别成为 span。一次排查发现工具返回了 HTTP 200 但 body 是错误提示，模型把字符串当成了订单信息。修复工具返回值校验后，同类型错误减少，token 成本也下降了。

验收清单

• 每次 Agent 运行有唯一 trace ID，并能跨日志查询。
• 模型调用、工具调用和外部请求都有 span。
• 日志包含完整消息上下文或明确标记未记录。
• token、延迟和成本挂到对应 span。
• 敏感字段已脱敏，导出内容不出现明文密钥。
• 错误、循环和成本告警已配置。
• 调试流程能在几分钟内定位失败步骤。

常见坑

• 只记录最终回答，不记录模型当时看到的消息。
• 把工具 HTTP 状态码当作成功，忽略 body 里的业务错误。
• 日志里保存完整 token 和 secret，观察系统反而变成泄漏源。
• 记录嵌入向量但不记录检索文本，排错时无法判断内容相关性。
• 把所有框架回调全量入库，真正有用的模型调用被淹没。

排错路径

• 找不到失败 trace：检查 trace ID 是否在入口生成，以及日志字段名是否一致。
• 模型答错但工具正常：查看该步 messages，确认上下文是否混入旧状态。
• 工具反复调用：检查相同参数连续次数，并设置步骤上限。
• token 突增：比较各步骤 messages 长度，定位把大文档塞进上下文的步骤。
• 日志有明文敏感数据：在导出前加 redactor，并立即删除已落盘的旧记录。

后续维护建议

更新日期：2026-08-20。每次新增模型、工具或检索源时，重新检查 span 字段和脱敏规则。每月审查一次 token 成本、trace 存储量和告警噪音。Agent 的指令或工具行为变化后，用固定测试用例回放历史 trace，确认可观测性没有因为框架升级而失效。

公开来源

1. OpenTelemetry Docs: Traces
2. OpenTelemetry Docs: Logs
3. Langfuse Docs: Tracing