AI Agent可观测性实践
1. 概述：为什么传统APM不够用
将AI Agent部署到生产环境后，第一个问题往往是：“它为什么这样回答？”
传统应用可观测性（APM）专注于HTTP状态码、响应时间、数据库查询。但AI Agent是概率系统，其”故障模式”与传统软件截然不同：
| 维度 | 传统APM | AI Agent可观测性 |
|---|---|---|
| 故障定义 | 异常抛出、5xx错误 | 幻觉、工具选择错误、循环 |
| 追踪对象 | 函数调用栈 | Prompt → LLM → Tool → Response |
| 关键指标 | QPS、延迟 | TTFT、Token速率、质量评分 |
| 调试方式 | 日志回溯 | Session重放、推理追踪 |
核心原则：如果你无法追踪它，就无法修复它；如果你无法修复它，就无法在生产环境运行它。
2. 全链路追踪架构
2.1 追踪ID体系
每个用户会话生成唯一trace_id，贯穿整个生命周期：
Trace ID: conv_abc123
├─ User message received [span 1]
├─ Prompt template rendered [span 2]
├─ LLM API call [span 3]
│ ├─ Model: gpt-4-turbo
│ ├─ Tokens: 450 input, 280 output
│ ├─ TTFT: 1.2s
│ └─ Duration: 3.4s
│ ├─ Tool selection: search_web [span 4]
│ │ └─ Tool result: 15KB
│ └─ Second LLM call with results [span 5]
└─ Response returned to user [span 6]
2.2 Span设计原则
每个Span应包含：
- 时间戳：精确到毫秒
- 输入/输出：完整的数据内容
- 元数据：模型版本、温度、token数
- 父子关系：完整的调用链
2.3 结构化日志设计
{
"timestamp": "2026-03-07T01:00:00Z",
"trace_id": "conv_abc123",
"session_id": "sess_456",
"user_id": "user_123",
"event": "llm_call",
"model": "gpt-4-turbo",
"prompt_tokens": 450,
"completion_tokens": 280,
"ttft_ms": 1200,
"duration_ms": 3400,
"cost_usd": 0.015
}3. 关键指标体系
3.1 延迟指标
| 指标 | 全称 | 含义 | 告警阈值 |
|---|---|---|---|
| TTFT | Time To First Token | 首个token响应时间 | >5s用户体验明显下降 |
| TBT | Time Between Tokens | Token间隔时间 | >500ms表示模型过载 |
| E2EL | End-to-End Latency | 完整请求响应时间 | 根据业务定义 |
3.2 吞吐量指标
| 指标 | 含义 | 监控意义 |
|---|---|---|
| TPS | Token吞吐量 | 模型利用率 |
| RPS | 请求吞吐量 | 容量规划 |
| 队列深度 | 等待处理请求数 | 背压检测 |
3.3 错误指标
# 常见错误类型
ERROR_TYPES = {
"rate_limit": "429 - 请求被限流",
"timeout": "模型响应超时",
"context_overflow": "上下文超限",
"invalid_response": "模型输出格式错误",
"tool_error": "工具执行失败"
}3.4 质量指标
| 指标 | 计算方式 | 业务意义 |
|---|---|---|
| 任务完成率 | 成功完成数/总请求数 | 核心业务指标 |
| 工具调用准确率 | 正确工具选择数/总调用数 | Agent能力指标 |
| 循环检测 | 单会话中重复模式 | 异常行为 |
4. 工具链对比
4.1 工具对比表
| 工具 | 定位 | 优势 | 劣势 | 推荐场景 |
|---|---|---|---|---|
| LangSmith | LangChain原生 | 深度集成、调试友好 | 强依赖LangChain | LangChain项目 |
| Langfuse | 开源替代 | 自托管、数据可控 | 需自行运维 | 隐私敏感企业 |
| Arize AI | 企业级平台 | 高级分析、漂移检测 | 成本较高 | 大规模部署 |
| Weights & Biases | 实验跟踪 | 模型评估强 | 非专为Agent设计 | ML实验 |
4.2 OpenTelemetry集成
对于需要统一可观测性栈的团队，OpenTelemetry是标准协议：
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
# 配置Tracer
provider = TracerProvider(
resource=Resource.create({
"service.name": "ai-agent",
"service.version": "1.0.0"
})
)
# 创建span
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent.llm.call") as span:
span.set_attribute("model", "gpt-4-turbo")
span.set_attribute("prompt_tokens", 450)
# ... 执行LLM调用4.3 工具选择建议
起步推荐：LangSmith或Langfuse（快速获得可见性）
扩展路径：当团队成熟后，迁移到自定义OpenTelemetry + 自建Dashboard
5. 最佳实践
5.1 从第一天开始
可观测性不是”以后再添加”的特性：
- Trace ID贯穿始终：每个请求、每个日志都携带trace_id
- Prompt版本控制：每次Prompt变更记录版本，与质量指标关联
- 捕获用户反馈： thumbs up/down、regenerate、correction flows
5.2 避免告警疲劳
只关注可操作的、业务影响的指标：
✅ 告警：任务完成率 < 80%（业务直接影响）
✅ 告警：单会话Token数 > 50000（成本影响）
❌ 不告警：单个LLM调用延迟波动10ms
5.3 常见错误
| 错误 | 后果 | 解决方案 |
|---|---|---|
| 只监控HTTP 200 | 200返回垃圾输出 | 监控输出质量 |
| 不追踪Prompt版本 | 质量下降无法溯源 | Prompt版本化 |
| 忽略成本监控 | 月末账单爆炸 | 实时成本仪表盘 |
6. 实施清单
生产AI Agent可观测性检查清单：
[ ] Trace ID生成与传递
[ ] 全链路span设计
[ ] TTFT/TBT/E2EL指标采集
[ ] Token用量与成本追踪
[ ] 错误分类与告警
[ ] Session级别关联
[ ] Prompt版本控制
[ ] 用户反馈捕获
[ ] Dashboard构建
[ ] 告警规则定义