Agent 可观测性：日志、链路追踪与指标监控

为什么 Agent 需要可观测性

Agent 是自主决策系统。如果不记录它在做什么，出了问题你根本不知道哪里坏了。

三大支柱：

1. 日志（Logging）：每次工具调用的输入输出
2. 链路追踪（Tracing）：一个请求跨多步的完整路径
3. 指标（Metrics）：成功率、延迟、Token 消耗

日志设计

结构化日志

function logToolCall(agent, tool, args, result, duration) {
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    agent: agent,
    tool: tool,
    args: JSON.stringify(args),
    result_preview: JSON.stringify(result).slice(0, 200),
    duration_ms: duration,
    status: result.error ? 'error' : 'success'
  }));
}

关键日志点

• 每次工具调用的输入和输出
• Agent 的决策过程（选择了哪个工具、为什么）
• 错误和重试
• Token 使用量

链路追踪

用 Trace ID 串联一次完整请求：

Trace: abc-123
  ├─ Step 1: user_query -> agent_decision (5ms)
  ├─ Step 2: tool_call: search(query="...") (320ms)
  ├─ Step 3: tool_call: weather(city="Shanghai") (180ms)
  └─ Step 4: generate_response (850ms)
  Total: 1355ms

指标监控

关键指标：

• 工具调用成功率（目标 > 95%）
• 平均响应延迟
• 每请求 Token 消耗
• 每日活跃用户数

实现方案

• 轻量：写文件 + 简单脚本分析
• 中量：OpenTelemetry + Jaeger
• 重量：Datadog / Grafana 全栈监控