告警指标参考
概述
本文面向 API 网关用户，介绍如何制定合理的告警规则，用户需要在 CProm 控制台完成相关告警配置。文中给出的阈值为通用推荐值，可作为初始配置，上线后请结合自身业务基线微调。
适用范围与通用约定
API 网关提供丰富的监控指标，但并非每个指标都适合设置固定阈值告警。本文将指标分为两类：
- 建议设置告警：具备通用健康阈值的指标（成功率、响应时间、5xx 比例），无论业务规模大小，偏离阈值都意味着异常。
- 不建议设置固定阈值：随业务规模线性变化的指标（QPS、PV、流量、访问量等），固定阈值容易在流量波动时误报或漏报，建议基于历史基线单独配置。
配置告警时的通用约定：
| 项 | 约定 | 说明 |
|---|---|---|
| 告警级别 | 警告（warning）/ 严重（critical） | 警告用于关注趋势，严重用于立即介入 |
| 评估窗口 | 5 分钟 | 每次评估回看最近 5 分钟的数据 |
| 持续时间 | 警告 10 分钟 / 严重 5 分钟 | 指标需连续超阈达到该时长才真正触发，避免瞬时抖动误报 |
| 低流量护栏 | 最近 5 分钟请求数 ≥ 10 | 请求过少时不评估比率类告警，避免个别请求把成功率/错误率放大 |
| 统计维度 | 按网关实例聚合 | 默认按部署实例聚合，单个节点滚动、重启不会误报 |
推荐设置的告警指标
下表为推荐设置的基础告警配置，覆盖「可用性」与「时延」两大类，可按需设置。
| 告警项 | 统计维度 | 级别 | 建议阈值 | 持续时间 | 触发含义 |
|---|---|---|---|---|---|
| 请求成功率 | 网关实例 | 警告 | < 95% | 10m | 实例整体成功率偏低 |
| 请求成功率 | 网关实例 | 严重 | < 90% | 5m | 实例整体成功率严重下降，需立即排查 |
| 请求成功率 | API（HTTP/Agent） | 警告 | < 95% | 10m | 单个 HTTP/Agent 路由成功率偏低 |
| 请求成功率 | 模型（Model） | 警告 | < 95% | 10m | 单个大模型调用成功率偏低 |
| P95 响应时间 | 网关实例 | 警告 | > 1000ms | 10m | HTTP/Agent 请求 P95 时延偏高 |
| P95 响应时间 | 网关实例 | 严重 | > 3000ms | 5m | HTTP/Agent 请求 P95 时延严重偏高 |
| P99 响应时间 | 网关实例 | 严重 | > 5000ms | 5m | HTTP/Agent 请求 P99 时延严重偏高 |
| P95 响应时间 | API（HTTP/Agent） | 警告 | > 1000ms | 10m | 单个路由 P95 时延偏高 |
| 5xx 比例 | 网关实例 | 警告 | > 2% | 10m | 实例服务端错误比例偏高 |
| 5xx 比例 | 网关实例 | 严重 | > 5% | 5m | 实例服务端错误比例严重偏高，需立即排查 |
| 5xx 比例 | API（HTTP/Agent） | 严重 | > 10% | 5m | 单个路由服务端错误比例严重偏高 |
| 5xx 比例 | 模型（Model） | 严重 | > 10% | 5m | 单个大模型调用服务端错误比例严重偏高 |
维度说明：HTTP 与 Agent 属于同一类「路由」流量，共用路由级告警，会自动按类型拆分为两组告警实例；Model（大模型调用）为独立一类。
指标详解
请求成功率
- 定义：成功请求数 ÷ 总请求数。成功指返回 2xx 状态码；3xx/4xx/5xx 及未知状态均记为失败。
- 推荐阈值：实例级 < 95% 报警告、< 90% 报严重；路由级、模型级 < 95% 报警告。
- 注意：大模型流式调用（SSE）若在返回首包后中断，仍可能被记为 2xx，导致成功率略偏乐观。若你的业务大量使用流式，建议同时关注「响应时间」和「5xx 比例」。
请求响应时间（P95 / P99）
- 定义：P95 表示 95% 的请求快于该值，P99 表示 99% 的请求快于该值。相比平均值，分位值更能反映长尾体验。
- 适用范围：仅统计 HTTP / Agent API 流量。大模型调用（Model）耗时天然较长且波动大，不纳入这套时延阈值。
- 推荐阈值：实例级 P95 > 1000ms 报警告、> 3000ms 报严重；实例级 P99 > 5000ms 报严重；单API P95 > 1000ms 报警告。
- 注意：Agent 类 API 可能在一次请求内多次调用大模型，时延天然偏高。如果某 Agent API 经常超阈但属正常，可单独为该路由放宽阈值。
5xx 比例
- 定义：返回 5xx（服务端错误）的请求数 ÷ 总请求数。区别于成功率，它只聚焦「服务端故障」，不受客户端 4xx 影响。
- 推荐阈值：实例级 > 2% 报警告、> 5% 报严重；路由级、模型级 > 10% 报严重。
- 用途：5xx 比例突增通常指向后端服务不可用、超时或网关自身异常，是排障的第一落点。
各告警项 PromQL 示例
以下为推荐告警对应的 PromQL 参考表达式，供使用自定义查询或 Prometheus 告警规则时参考。 通用口径：评估窗口
5m；按网关实例（namespace）聚合；比率类末尾加>= 10低流量护栏（近 5 分钟请求数不足 10 则不评估）；比率类（成功率、5xx）用increase()，分位类（P95/P99）用rate()；失败定义为非 2xx（status_class=~"3xx|4xx|5xx|unknown"）。 指标族说明：HTTP/Agent 属 route 族（aigw_route_requests_total），大模型调用属 model 族（aigw_model_requests_total），实例级需用{__name__=~"aigw_route_requests_total|aigw_model_requests_total"}合并两族。
请求成功率
实例请求成功率 < 95%（警告，10m）
实例最近 5 分钟至少有 10 个请求，且非 2xx 比例连续 10 分钟超过 5%（即成功率低于 95%）。
1(
2 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total", status_class=~"3xx|4xx|5xx|unknown"}[5m]))
3 /
4 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m]))
5) * 100 > 5
6and sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m])) >= 10实例请求成功率 < 90%（严重，5m）
实例最近 5 分钟至少有 10 个请求，且非 2xx 比例连续 5 分钟超过 10%（即成功率低于 90%），需要立即排查。
1(
2 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total", status_class=~"3xx|4xx|5xx|unknown"}[5m]))
3 /
4 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m]))
5) * 100 > 10
6and sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m])) >= 10API（HTTP/Agent）请求成功率 < 95%（警告，10m）
单个 HTTP/Agent API 最近 5 分钟至少有 10 个请求，且成功率连续 10 分钟低于 95%。
1(
2 sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total{status_class=~"3xx|4xx|5xx|unknown"}[5m]))
3 /
4 sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total[5m]))
5) * 100 > 5
6and sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total[5m])) >= 10模型（Model）请求成功率 < 95%（警告，10m）
单个 Model 最近 5 分钟至少有 10 个请求，且成功率连续 10 分钟低于 95%。
1(
2 sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total{status_class=~"3xx|4xx|5xx|unknown"}[5m]))
3 /
4 sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total[5m]))
5) * 100 > 5
6and sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total[5m])) >= 10注：模型流式调用「200 后中断」仍记为 2xx，成功率可能系统性偏高，请结合响应时间/5xx 综合判断。
请求响应时间（仅 HTTP/Agent 路由）
实例 P95 > 1000ms（警告，10m）
实例最近 5 分钟至少有 10 个 HTTP/Agent 时延样本，且 P95 连续 10 分钟超过 1000ms。
1histogram_quantile(0.95, sum by (namespace, le) (rate(aigw_route_request_duration_milliseconds_bucket[5m]))) > 1000
2and sum by (namespace) (increase(aigw_route_request_duration_milliseconds_count[5m])) >= 10实例 P95 > 3000ms（严重，5m）
实例最近 5 分钟至少有 10 个 HTTP/Agent 时延样本，且 P95 连续 5 分钟超过 3000ms。
1histogram_quantile(0.95, sum by (namespace, le) (rate(aigw_route_request_duration_milliseconds_bucket[5m]))) > 3000
2and sum by (namespace) (increase(aigw_route_request_duration_milliseconds_count[5m])) >= 10实例 P99 > 5000ms（严重，5m）
实例最近 5 分钟至少有 10 个 HTTP/Agent 时延样本，且 P99 连续 5 分钟超过 5000ms。
1histogram_quantile(0.99, sum by (namespace, le) (rate(aigw_route_request_duration_milliseconds_bucket[5m]))) > 5000
2and sum by (namespace) (increase(aigw_route_request_duration_milliseconds_count[5m])) >= 10API P95 > 1000ms（警告，10m）
单个 HTTP/Agent API 最近 5 分钟至少有 10 个时延样本，且 P95 连续 10 分钟超过 1000ms。
1histogram_quantile(0.95, sum by (namespace, service_type, domain_id, service_id, api_id, le) (rate(aigw_route_request_duration_milliseconds_bucket[5m]))) > 1000
2and sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_request_duration_milliseconds_count[5m])) >= 10注：Agent 单次请求可能串联多次模型调用，时延天然偏高，如属正常可为该路由单独放宽阈值。大模型调用（Model）的总响应时间随输出长度线性变化，无通用阈值，不纳入此类告警。
5xx 比例
实例 5xx 比例 > 2%（警告，10m）
实例最近 5 分钟至少有 10 个请求，且 5xx 比例连续 10 分钟超过 2%。
1(
2 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total", status_class="5xx"}[5m]))
3 /
4 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m]))
5) * 100 > 2
6and sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m])) >= 10实例 5xx 比例 > 5%（严重，5m）
实例最近 5 分钟至少有 10 个请求，且 5xx 比例连续 5 分钟超过 5%，需要立即排查。
1(
2 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total", status_class="5xx"}[5m]))
3 /
4 sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m]))
5) * 100 > 5
6and sum by (namespace) (increase({__name__=~"aigw_route_requests_total|aigw_model_requests_total"}[5m])) >= 10路由 5xx 比例 > 10%（严重，5m）
单个 HTTP/Agent API 最近 5 分钟至少有 10 个请求，且 5xx 比例连续 5 分钟超过 10%。
1(
2 sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total{status_class="5xx"}[5m]))
3 /
4 sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total[5m]))
5) * 100 > 10
6and sum by (namespace, service_type, domain_id, service_id, api_id) (increase(aigw_route_requests_total[5m])) >= 10模型 5xx 比例 > 10%（严重，5m）
单个 Model 最近 5 分钟至少有 10 个请求，且 5xx 比例连续 5 分钟超过 10%。
1(
2 sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total{status_class="5xx"}[5m]))
3 /
4 sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total[5m]))
5) * 100 > 10
6and sum by (namespace, domain_id, service_id, model_id) (increase(aigw_model_requests_total[5m])) >= 10提示：以上表达式中的
> 5/> 10是「失败/5xx 比例超过 N%」的判定，与成功率阈值互为补集（成功率 < 95% ⇔ 失败率 > 5%）。
评价此篇文章