🎯 今日核心问题

  1. 哪几类异常必须立刻把电话打到你手机上,哪些只需要进日报?
  2. 为什么「连续 5 分钟错误率 > 5%」这种规则会天天误报,而「环比跌幅」反而更可靠?
  3. 成本类告警怎么设,才能在上线当天下午就发现「这一版 Prompt 让成本翻了 3 倍」?

📖 精读提纲

【一】按「可逆性」分三级,而不是按「严重程度」

告警设计最常见的失败是把所有指标都用同一个阈值逻辑,结果是 200 条告警里 190 条被静音。正确的分类维度是可逆性:造成资损或不可撤销动作的(P1,立刻打电话)、会造成用户可见质量下降但可恢复的(P2,企业微信 15 分钟内处理)、只是趋势变差的(P3,进日报)。

P1 只有四条:①钱包级成本异常(10 分钟内成本环比 > 3 倍)、②写工具失败率骤升(退款/下单类工具 5 分钟内失败率 > 2%)、③幻觉守卫拦截率跳变(超过基线 3 倍,说明模型或 Prompt 出了大问题)、④全部模型供应商不可用。这四条的共同点是:继续跑下去会持续造成不可撤销的损害。

【二】用「比率 + 短窗口 + 最小样本量」压制误报

「5 分钟内错误率 > 5%」在流量低谷时必然误报——凌晨 3 点只有 4 个请求,错 1 个就是 25%。所以每条比率型告警必须带最小样本门槛:rate(...) > 0.05 AND sum(increase(total[5m])) >= 50。同时窗口要短(5m)、for 要短(2m),宁可漏一次也别天天叫——被静音的告警等于不存在。

另一条经验:用环比而不是绝对值。成功率 97% 是好是坏取决于它昨天是 99.2% 还是 96.8%。所以成功率告警写成「当前 1 小时成功率比前 24 小时基线低 3 个百分点」,比一个硬阈值灵敏得多,而且能自适应业务形态。

【三】Agent 特有的一类告警:行为异常

传统监控看「接口对不对」,Agent 还得看「它做的事对不对」。四类行为告警值得单独设:① 平均步数比 7 日基线涨 40%(工具返回格式变化的第一信号);② 同一 trace 内重复调用同一工具 3 次以上(模型陷入循环,往往是工具报错但错误信息模型读不懂);③ 最大步数触顶率 > 1%(能力不足或 Prompt 缺收尾指令);④ 越权尝试:模型请求了不在白名单里的工具名,任何一次都要告警——这不是 bug,是攻击信号。

【四】成本告警的三种粒度

只看日账单太晚。要三层:单请求级(单次成本 > P99.9 的 5 倍,通常是某个 Prompt 把整篇文档塞进去了)、请求集合级(10 分钟聚合成本环比 3 倍,抓上线变更)、预算级(日预算消耗到 70%/90% 各报一次,用 predict_linear 预测当天是否超支)。第三层最有价值:中午 12 点就能知道今天会超。

【五】告警必须带「下一步做什么」

一条合格的告警消息包含:当前值、基线值、影响范围(哪个 agent / 哪个工具 / 多少用户)、一条可点的 Grafana 链接、以及一句 Runbook 指令(「先看 agent.router.decision 的 tier 分布,若 large 占比涨了,回滚 Prompt 版本」)。没有 Runbook 的告警会让人在凌晨三点打开 dashboard 发呆。

💻 代码示例

Spring Boot Actuator 暴露 Prometheus 端点(这是前提,很多人漏了 histogram):

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,metrics
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: ${spring.application.name}
      env: ${ENV:dev}
    distribution:
      percentiles-histogram:
        agent.task.duration: true
      slo:
        agent.task.duration: 800ms,2s,5s,15s,30s

告警规则文件 prometheus/rules/agent.yml,四条 P1 + 三条行为告警:

groups:
  - name: agent-p1
    rules:
      - alert: AgentCostSpike
        expr: |
          sum(rate(agent_cost_microusd_total[10m]))
            / sum(rate(agent_cost_microusd_total[10m] offset 1h)) > 3
          and sum(increase(agent_task_total[10m])) >= 20
        for: 5m
        labels: { severity: p1, runbook: "cost-spike" }
        annotations:
          summary: "10 分钟成本是 1 小时前的 {{ $value }} 倍"
          action: "查 agent.router.decision 的 tier 分布;若 large 占比上升则回滚 Prompt 版本"

      - alert: WriteToolFailureRate
        expr: |
          sum(rate(agent_tool_total{side_effect!="READ_ONLY",outcome!="success"}[5m]))
            / sum(rate(agent_tool_total{side_effect!="READ_ONLY"}[5m])) > 0.02
          and sum(increase(agent_tool_total{side_effect!="READ_ONLY"}[5m])) >= 20
        for: 2m
        labels: { severity: p1, runbook: "write-tool-down" }
        annotations:
          summary: "写工具失败率 {{ $value | humanizePercentage }}"

      - alert: HallucinationGuardSurge
        expr: |
          sum(rate(agent_guard_hit_total[15m]))
            > 3 * sum(rate(agent_guard_hit_total[15m] offset 1d))
        for: 10m
        labels: { severity: p1, runbook: "guard-surge" }
        annotations:
          summary: "幻觉守卫拦截率是昨日同期 3 倍以上"

      - alert: AllProvidersDown
        expr: |
          sum(rate(gen_ai_chat_total{outcome="success"}[5m])) == 0
          and sum(increase(gen_ai_chat_total[5m])) > 0
        for: 2m
        labels: { severity: p1, runbook: "provider-down" }

  - name: agent-behavior
    rules:
      - alert: AgentStepInflation
        expr: |
          sum(rate(agent_task_steps_sum[30m])) / sum(rate(agent_task_steps_count[30m]))
            > 1.4 * (sum(rate(agent_task_steps_sum[30m] offset 1d))
                       / sum(rate(agent_task_steps_count[30m] offset 1d)))
        for: 15m
        labels: { severity: p2, runbook: "step-inflation" }
        annotations:
          summary: "平均步数比昨日同期高 40%,怀疑工具返回格式变更"

      - alert: MaxStepsHitRate
        expr: |
          sum(rate(agent_task_total{outcome="max_steps"}[15m])) / sum(rate(agent_task_total[15m])) > 0.01
        for: 10m
        labels: { severity: p2 }

      - alert: UnauthorizedToolAttempt
        expr: increase(agent_tool_denied_total[5m]) > 0
        labels: { severity: p1, runbook: "tool-denied" }
        annotations:
          summary: "模型请求了未授权的工具,可能是提示注入攻击"

告警消息里带上影响范围,靠一个小的 AlertContext 补充业务维度(Prometheus 的 alert 注解自己拿不到这些):

@Component
@RequiredArgsConstructor
public class AlertEnricher {

    private final PrometheusClient prom;

    public Map<String, String> enrich(String alertName) {
        long failed = prom.scalar("sum(increase(agent_task_total{outcome!="success"}[10m]))");
        long users = prom.scalar("count(count by (user_key) (agent_task_total[10m]))");
        return Map.of(
                "failedTasks10m", String.valueOf(failed),
                "affectedUsers10m", String.valueOf(users),
                "grafana", "https://grafana.internal/d/agent-ops?var-alert=" + alertName,
                "dashboardHints", "router.decision / gen_ai.chat.duration / agent.cost.microusd");
    }
}

✏️ 今日动手

把上面 7 条规则落到 prometheus/rules/agent.yml,用 promtool check rules 校验语法,然后逐条造故障验证:把 Prompt 里塞一篇 2 万字文档(触 CostSpike)、mock 写工具返回 500(触 WriteToolFailureRate)、把某个工具返回值改字段名(触 AgentStepInflation)。每条都要验证「多久触发、消息里有没有 Runbook 链接」。没验证过的告警等于没有告警。

🔖 明日预告

本周收尾:把拦截器、指标、日志、成本、告警拼成一个可观测 Agent 的完整实现,附上周回顾表与下周(W8 多 Agent 协作)的入口。