监控方案

可观测性不是「加个日志」，而是指标、日志、链路追踪三者打通，能回答「现在系统怎么样」和「刚才发生了什么」。

监控三大支柱

graph TD
  O[可观测性] --> M[Metrics 指标]
  O --> L[Logs 日志]
  O --> T[Tracing 链路]
  M --> R[RED/USE]
  L --> TR[trace_id 关联]
  T --> SP[span 分段耗时]

1. Metrics（指标）

• 黄金指标：RED（请求量/错误/延迟）+ USE（利用率/饱和度/错误）
• Agent 特有指标：TTFT、TPOT、转人工率、工具成功率、无依据承诺率

2. Logs（日志）

• 统一 stdout 输出
• 每行带 trace_id，可串起一轮对话的完整链路
• 级别用 LOG_LEVEL 环境变量控制

3. Tracing（链路）

• 分段埋点：Frontend → Gateway → App → Retrieval/Tool → LLM → DB
• 每个 span 记录耗时，找最长 span 定位瓶颈

实战落地（智能客服 Agent）

graph LR
  A[对话事件] --> B[evaluation_events<br/>MySQL 持久化]
  B --> C[GET /metrics<br/>Prometheus 文本]
  C --> D[Grafana 面板]
  B --> E[滑动窗口阈值判定]
  E --> F[告警落库 + webhook]

• 指标埋点：每轮对话记录 evaluation_events（意图/响应模式/引用校验/转人工/时延）
• 指标暴露：GET /metrics 输出 Prometheus 文本，前缀 cs_eval_
• 告警：转人工率 / 出错率 / 无依据承诺率 三项滑动窗口阈值判定，命中落库 + 可选 webhook
• 阈值可配：ALERT_HANDOFF_RATE / ALERT_ERROR_RATE / ALERT_UNFOUNDED_RATE

trace_id 链路排查

• 每个 HTTP 请求响应头带 X-Request-ID
• SSE 流式请求全程同一个 ID
• 从日志按 trace_id 串起「消息进入 → 混合检索 → LLM 生成 → 回答落库/转人工」