4. PromQL 基础：即时查询与范围查询、常用函数
在容量规划基线对比中，PromQL 是分析历史数据、评估当前状态的核心工具。本章聚焦于 PromQL 的两种查询模式与四个最常用的函数，帮助你在网关升级场景中准确提取指标特征。
4.1 即时查询 vs 范围查询
PromQL 的查询结果类型决定了你能获取“一个时间点的快照”还是“一段时间内的序列”。理解这一区别是正确使用函数的前提。
| 特性 | 即时查询 (Instant Query) | 范围查询 (Range Query) |
|---|---|---|
| 返回结果 | 每个时间序列一个样本值 | 每个时间序列一组有序样本 |
| 语法特征 | 直接写指标名或表达式 | 指标名后加 [持续时间] |
| 典型用途 | 当前 CPU 使用率、实时告警 | 过去 5 分钟平均延迟、增长率 |
| 容量规划场景 | 查看当前连接数是否超限 | 对比升级前后一周的流量趋势 |
关键区别： 范围查询必须配合
rate、increase、avg_over_time 等函数使用，否则返回的原始样本数组无法直接用于计算。
查询示例对比
# 即时查询：当前网关请求速率（假设 scrape_interval=15s）
rate(gateway_requests_total[1m])
# 范围查询：过去 1 小时的原始样本（通常不直接使用）
gateway_requests_total[1h]
实践建议： 在 Grafana 面板中，即时查询用于 Stat/Guage 面板，范围查询配合
$__range 变量用于 Time series 面板。
4.2 常用函数详解
以下四个函数是容量规划基线对比中使用频率最高的 PromQL 函数。每个函数都依赖范围查询提供的数据窗口。
4.2.1 rate() — 计算每秒平均增长率
rate(v range-vector) 计算区间向量中时间序列的每秒平均增长率，自动处理计数器重置（如服务重启导致指标归零）。
# 网关每秒请求数（基于 5 分钟窗口）
rate(gateway_requests_total[5m])
# 升级前后对比示例（假设已记录两个版本）
rate(gateway_requests_total{version="v2.0"}[5m]) -
rate(gateway_requests_total{version="v1.0"}[5m])
⚠ 常见错误： 对 Gauge 类型指标使用
rate()。Gauge 应使用 avg_over_time() 或 delta()。
4.2.2 increase() — 计算时间窗口内的增量
increase(v range-vector) 返回区间向量中时间序列在给定时间窗口内的增量。与 rate() 的关系：increase = rate * 窗口秒数。
| 场景 | 推荐函数 | 原因 |
|---|---|---|
| 评估每秒流量 | rate() |
标准化到秒，便于不同窗口对比 |
| 计算总请求量 | increase() |
直接得到窗口内的增量 |
| 容量规划基线 | rate() |
更容易与资源配额（QPS）对齐 |
# 过去 1 小时网关处理的总请求数
increase(gateway_requests_total[1h])
# 升级后 24 小时相比升级前 24 小时的请求增量
increase(gateway_requests_total{version="v2.0"}[24h]) -
increase(gateway_requests_total{version="v1.0"}[24h])4.2.3 avg() 与 max() — 聚合运算
avg() 和 max() 是聚合运算符，用于将多个时间序列合并为一个。在容量规划中，它们常与 by 子句配合使用。
# 所有网关实例的平均 CPU 使用率
avg(node_cpu_seconds_total{mode="user"}) by (instance)
# 集群中最大内存使用量（用于评估峰值需求）
max(container_memory_usage_bytes{namespace="gateway"}) by (pod)
容量规划基线对比技巧： 使用
avg() 观察整体趋势，使用 max() 识别瓶颈实例。升级后若 max() 下降而 avg() 不变，说明负载分布更均衡。
4.2.4 quantile_over_time() — 时间窗口内的分位数
quantile_over_time(scalar, range-vector) 计算区间向量中每个序列在时间窗口内的指定分位数。这是评估延迟分布、识别长尾问题的关键函数。
# 过去 5 分钟网关响应延迟的 P99
quantile_over_time(0.99, gateway_response_duration_seconds[5m])
# 升级前后 P50、P95、P99 对比
quantile_over_time(0.50, gateway_response_duration_seconds{version="v2.0"}[5m])
quantile_over_time(0.95, gateway_response_duration_seconds{version="v2.0"}[5m])
quantile_over_time(0.99, gateway_response_duration_seconds{version="v2.0"}[5m])4.3 函数组合实战：升级基线对比
在网关升级容量规划中，通常需要组合多个函数来构建完整的基线对比视图。以下是一个典型查询示例：
# 升级后 vs 升级前：P99 延迟变化率（单位：%）
(
quantile_over_time(0.99, gateway_response_duration_seconds{version="v2.0"}[5m])
-
quantile_over_time(0.99, gateway_response_duration_seconds{version="v1.0"}[5m])
)
/
quantile_over_time(0.99, gateway_response_duration_seconds{version="v1.0"}[5m])
* 100
基线对比原则： 始终使用相同的窗口长度（如 [5m]）和相同的聚合方式。窗口过短（如 [30s]）会导致数据抖动，过长（如 [1h]）会掩盖瞬时峰值。
4.4 本章小结
- 即时查询 返回单点快照，适合实时监控；范围查询 返回时间序列，是函数计算的基础。
rate()用于计算每秒增长率，是 QPS 基线分析的首选；increase()用于计算窗口内增量。avg()和max()配合by子句实现多实例聚合，评估整体与瓶颈。quantile_over_time()是延迟分布分析的核心工具，直接支撑 P50/P95/P99 基线对比。