生产环境可观测性

为何比普通 API 更难

一次用户提问可能触发多轮 LLM、多次工具、子 Agent，失败点分散。没有统一 trace，只能看到「超时」，看不到是第 3 次工具 SQL 慢还是模型重试。可观测性要把决策过程变成可查询数据。

结构化日志

每条记录建议字段：

{
  "trace_id": "abc123",
  "session_id": "sess_9",
  "span": "tool:run_sql",
  "prompt_id": "analyst_system",
  "prompt_version": "1.4.0",
  "model": "gpt-4o",
  "input_tokens": 2100,
  "output_tokens": 340,
  "latency_ms": 1820,
  "status": "ok"
}

禁止记录完整用户 PII 或密钥；Prompt 可哈希或采样存储。工具参数脱敏后入库。

分布式追踪

用 OpenTelemetry：入口创建 root span，llm.chat 与 tool.invoke 为子 span，标注 error.type。Jaeger/Tempo 上可看到：

HTTP POST /chat
  └─ agent.run (2.1s)
       ├─ llm.completion #1 (800ms)
       ├─ tool.search (400ms)
       └─ llm.completion #2 (900ms)

指标与告警

| 指标 | 用途 | |---|---| | agent_requests_total | QPS | | agent_errors_total by code | 错误率 | | llm_tokens_total by model | 成本 | | tool_latency_seconds histogram | 慢工具 | | guardrail_blocks_total | 安全拦截 |

告警示例：5 分钟错误率 > 5%、P95 延迟 > 30s、单用户 Token 突增 10 倍（可能死循环）。

评测与线上联动

离线评测集定期跑；线上黄金路径合成探测（canary prompt）每小时执行。版本发布关联 dashboard 看板，劣化自动回滚 Prompt 指针。

落地清单

• 统一 trace_id 贯穿网关、Agent、工具、LLM 代理
• Dashboard：成本、成功率、TTFT、Top 慢工具
• 事故 runbook：如何按 session 重放 messages（脱敏）

可观测性让 Agent 从「黑盒对话」变成可运维系统，是团队规模化协作的前提。