PromQL 劝退的不是难度,是没人先给你模板
PromQL 第一次看很像把 SQL、正则表达式和数学函数揉在了一起:括号套括号,标签一长串,最后还分不清为什么查询结果是空的。其实它没有那么神秘,大多数日常查询只是在重复几件事:先按标签选出指标,再对 Counter 计算变化率,接着聚合、做除法,最后得到使用率、吞吐量或错误比例。
所以这篇不从抽象语法开始背,而是先把常用模板摆出来,再回头解释每个部件。配合上一篇的 Node Exporter 指标和Prometheus 基础,你可以直接把模板放进 Grafana 面板或告警规则里改标签使用。
PromQL 的核心顺序只有一句:先选对指标和标签,再选对函数,最后才做聚合与运算。
参考文档:https://prometheus.io/docs/prometheus/latest/querying/basics/
先认清四种数据
PromQL 表达式的结果主要有四种类型。先分清它们,很多“为什么不能这样写”的问题就自动消失了。
| 类型 | 含义 | 例子 |
|---|---|---|
| 瞬时向量(Instant Vector) | 某一时刻的一组时间序列 | node_cpu_seconds_total{mode="idle"} |
| 区间向量(Range Vector) | 一段时间范围内的一组样本 | node_cpu_seconds_total[5m] |
| 标量(Scalar) | 一个没有标签的数字 | time()、42 |
| 字符串(String) | 一段文本,使用场景很有限 | "ready" |
最容易混淆的是前两种。up 是瞬时向量,表示查询时刻每条序列的值;up[5m] 是区间向量,表示过去 5 分钟内的样本集合。区间向量通常不能直接画成一条普通曲线,它更像是交给 rate()、increase()、avg_over_time() 等函数的原材料。
指标名本身也是一种标签选择。Prometheus 内部把指标名存放在 __name__ 标签中,所以选择器本质上是在按标签筛选时间序列。
选择器与标签匹配:先把范围缩小
选择器由指标名和花括号中的标签条件组成:
node_network_receive_bytes_total{ instance="server-01:9100", device!="lo", device!~"veth.*|docker.*"}四种标签匹配符必须分清:
| 匹配符 | 含义 | 典型用途 |
|---|---|---|
= | 完全相等 | 固定实例、状态码、磁盘设备 |
!= | 不相等 | 排除空闲模式或回环网卡 |
=~ | 正则匹配 | 一次匹配多个状态码或设备 |
!~ | 正则不匹配 | 排除一组临时设备 |
有三个细节值得记住。第一,PromQL 的正则表达式是完全锚定的,device=~"eth" 只匹配值恰好为 eth 的标签,不会匹配 eth0,应写成 device=~"eth.*" 或 device=~"eth.+"。第二,负向匹配可能选中“根本没有这个标签”的序列,所以排除前最好先在 Explore 里看看结果包含哪些序列。第三,不要一上来就用过宽的正则扫描高基数标签,查询范围越大,Prometheus 的计算压力越高。
例如,HTTP 5xx 状态码可以写成:
http_requests_total{status=~"5.."}这里的 5.. 表示以 5 开头、后面跟任意两个字符,比逐个列出 500、502、503 更简洁。
区间向量与 rate():Counter 的正确打开方式
Counter 是只增不减的累计值,例如进程启动以来收到的总字节数、处理过的总请求数。直接看 Counter 的绝对值通常没意义,我们关心的是单位时间增加了多少,这正是 rate() 的工作:
rate(http_requests_total[5m])它计算区间内每秒平均增长量。increase() 则估算整个区间内的总增量,两者关系可以近似理解为:
increase(http_requests_total[5m])# 约等于 rate(http_requests_total[5m]) * 300irate() 同样计算每秒速率,但只取最后两个样本,反应更灵敏,噪声也更大。看长期趋势、做告警,优先用 rate();观察刚刚发生的尖峰,才考虑 irate()。
Prometheus 会自动处理 Counter 重置。进程重启后 Counter 从 0 重新计数,rate() 会把这种下降识别为重置并进行修正,你不需要自己写判断。但自动处理不等于没有限制:区间里至少要有两个样本,函数才能算出变化;样本太少时,结果可能为空或不稳定。Prometheus 还会对区间两端做外推,因此 increase() 的结果可能不是整数,它表示估算增量,不是账本式的精确计数。
WARNING
rate()的时间窗口建议至少是抓取间隔的 4 倍。抓取间隔为 15 秒时,不要用[15s]或[30s],至少用[1m],日常面板和告警更推荐[5m]:窗口太短不仅容易没样本,还会把曲线画得剧烈抖动。
还有一条铁律:不要对 Gauge 使用 rate()。Gauge 是可上可下的瞬时值,例如内存可用量、温度、队列长度。对它求“每秒增长”没有业务含义;要看平均值、最大值或最小值,应使用 avg_over_time()、max_over_time()、min_over_time()。
聚合:先决定保留哪些标签
聚合函数把多条序列合并。常用的是 sum、avg、max、min 和 count。真正的难点不在函数,而在聚合后保留哪些标签。
sum by (instance) ( rate(node_cpu_seconds_total{mode="idle"}[5m]))
sum without (cpu, mode) ( rate(node_cpu_seconds_total[5m]))by 表示“只保留列出的标签”,without 表示“删掉列出的标签,其余都保留”。计算整台机器的 CPU 时,通常要去掉 cpu 和 mode,但保留 instance;计算整个集群总量时,才继续去掉 instance。
写聚合前先问一句:结果里的每条序列应该代表什么?一台机器、一个接口,还是一个服务?答案决定 by 里留什么。
如果把维度丢错,结果会悄悄变质。例如统计 HTTP 请求时写了 sum by (status),你只能看到各状态码总量,看不到每个接口的错误分布;反过来,保留了 path、user_id 这类高基数标签,又可能生成成千上万条序列,面板难读,查询也慢。
算术与比较运算:比例和阈值都靠它们
PromQL 支持 +、-、*、/、% 和 ^。最常见的用法是两个相同口径的量做除法,得到使用率或错误比例:
sum(rate(http_requests_total{status=~"5.."}[5m]))/sum(rate(http_requests_total[5m]))默认情况下,向量与向量运算会按相同标签集合进行匹配。两边的标签不一致时,Prometheus 可能返回空结果,或者直接报向量匹配错误。做除法前先用聚合把两边整理到相同维度,是最稳妥的办法。
比较运算符默认起“过滤器”作用:
node_filesystem_avail_bytes / node_filesystem_size_bytes < 0.1它只返回满足条件、也就是磁盘剩余不足 10% 的序列,原值仍然保留。加上 bool 修饰符后,它不再过滤,而是把结果改写成 0 或 1:
( node_filesystem_avail_bytes / node_filesystem_size_bytes < bool 0.1)前一种写法适合在 Grafana 里只看异常对象,后一种适合把“是否异常”作为 0/1 曲线或进一步参与计算。把阈值规则真正发送成通知,还要交给Alertmanager处理。
用 histogram_quantile() 计算 p95 与 p99
平均延迟最会骗人:99 个请求只要 10ms,1 个请求慢到 5 秒,平均值看起来仍然不高。观察延迟应该看分位数,而分位数要基于 Histogram 指标的 _bucket 序列计算。
Histogram 的 bucket 是累计计数,每个 bucket 带一个 le 标签,表示“小于等于这个秒数”。计算 p95 的标准姿势是先对 bucket 做 rate(),再按 le 聚合,最后交给 histogram_quantile():
histogram_quantile( 0.95, sum by (le) ( rate(http_request_duration_seconds_bucket[5m]) ))p99 只需把第一个参数换成 0.99。如果要按服务或接口拆分,就在 by 中同时保留业务标签和 le,例如 sum by (service, le)。聚合 bucket 时绝不能丢掉 le 标签,没有它,Prometheus 就不知道每个 bucket 的上界,分位数自然算不出来。
还要注意,histogram_quantile() 是根据 bucket 分布估算分位数,不是把每一次请求耗时排序后取精确值。bucket 划分越合理,估算越可信;如果绝大多数请求都落进同一个宽 bucket,结果只能看趋势,不能当成精密测量。
offset 与 @:看过去,钉住某个时刻
offset 可以把查询整体往过去平移,例如用今天的请求量和一周前对比:sum(rate(http_requests_total[5m] offset 7d))。@ 修饰符则把选择器固定到某个时间点,常用于报表和可复现查询。这两个修饰符在日常面板里用得不多,知道它们解决的是“时间位置”问题即可。
可直接抄的 PromQL 模板
下面的模板以 Node Exporter、Prometheus HTTP 指标和 kube-state-metrics 的常见命名为例。真正使用时,先把指标名粘到 Prometheus Explore 中确认存在,再替换实例、设备和接口标签。将这些模板做成面板变量后,就能配合Grafana快速切换服务器。
| 场景 | PromQL 模板 | 解读 |
|---|---|---|
| CPU 使用率 | 100 * (1 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m]))) | 用 100% 减去空闲比例,按实例保留一条曲线。 |
| 内存使用率 | 100 * (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) | 用内核估算的可用内存计算,比简单拿空闲内存更符合实际。 |
| 磁盘剩余比例 | 100 * node_filesystem_avail_bytes{fstype!~"tmpfs|overlay|squashfs"} / node_filesystem_size_bytes{fstype!~"tmpfs|overlay|squashfs"} | 排除临时文件系统后看每个挂载点还剩多少空间。 |
| inode 剩余比例 | 100 * node_filesystem_files_free{fstype!~"tmpfs|overlay"} / node_filesystem_files{fstype!~"tmpfs|overlay"} | 空间没满但 inode 耗尽同样无法创建文件,这条要和容量一起看。 |
| 网络接收吞吐 | sum by (instance) (rate(node_network_receive_bytes_total{device!~"lo|veth.*|docker.*"}[5m])) | 单位是字节每秒,排除回环和容器虚拟网卡后更接近物理流量。 |
| 网络发送吞吐 | sum by (instance) (rate(node_network_transmit_bytes_total{device!~"lo|veth.*|docker.*"}[5m])) | 与接收吞吐分开看,才能发现单向跑满或异常外发。 |
| 磁盘读写吞吐 | sum by (instance, device) (rate(node_disk_read_bytes_total{device!~"loop.*|dm-.*"}[5m])) | 把模板中的 read 换成 written 可看写入,保留 device 便于定位是哪块盘忙。 |
| 磁盘 IOPS | sum by (instance, device) (rate(node_disk_reads_completed_total[5m]) + rate(node_disk_writes_completed_total[5m])) | 读写次数合并后表示每秒完成的 I/O 操作数。 |
| HTTP 请求量 | sum by (method, status) (rate(http_requests_total[5m])) | 结果是每秒请求数,按方法和状态码拆分最容易看出流量结构。 |
| HTTP 5xx 比例 | 100 * sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) | 分子和分母都先聚合成同一维度,再相除得到整体错误率。 |
| HTTP p95 延迟 | histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m]))) | 表示约 95% 的请求不慢于这个估算值,适合做服务质量面板。 |
| 容器重启次数 | sum by (namespace, pod, container) (increase(kube_pod_container_status_restarts_total[1h])) | 统计过去 1 小时各容器重启增量,持续增长通常意味着 CrashLoop。 |
有三个使用习惯能省掉很多调试时间。第一,先查原始指标,再逐层往外加函数,出错时逐段删,定位到底是哪一层把结果弄空。第二,吞吐量模板返回的单位多半是 bytes/s,Grafana 里还要设置单位为 bytes/s,别把字节误读成 bit。第三,模板里的 [5m] 不是圣旨:抓取间隔是 30 秒或 1 分钟的系统,应相应放大窗口。
常见错误:三个新手高频坑
1. 对 Gauge 使用 rate()
看到指标名里有 total 不一定就是 Counter,也不能只凭名字判断。应查看指标的 HELP 和 TYPE,或观察一段时间:进程重启后会清零、长期只增的才是 Counter。内存、温度、连接数、队列深度这类当前值是 Gauge,想看趋势直接画原值,想看一段时间均值用 avg_over_time()。
2. rate() 窗口小于或贴近抓取间隔
如果 Prometheus 每 15 秒抓一次,却写 rate(metric[20s]),窗口内可能只有一个样本,结果就会断断续续。更隐蔽的是 [1m] 虽然能算,却对短时抖动极其敏感,告警会频繁触发又恢复。面板求稳用 5m,告警更要配合持续时间,不要拿几十秒的窗口追每一个毛刺。
3. sum 时把标签维度丢错
sum(metric) 会把所有序列合成一个总数,省事但丢信息;sum by (instance) 保留机器维度,却可能在聚合前把同一机器的 CPU 核、状态码或设备加在一起。错误通常不是语法报错,而是图“能出,但不对”。写完聚合后,检查结果的标签集合:每条序列是否正好对应你想观察的对象?如果不是,调整 by 或 without,不要靠改图例掩盖问题。
另外两个小坑也经常出现:一是正则忘了完全锚定,device=~"eth" 查不到 eth0;二是做除法时两边标签不一致,分子按接口聚合、分母却保留状态码,结果为空。遇到空结果时,分别单独运行分子和分母,看标签差异最有效。
小结
PromQL 不需要一次学完。日常工作里,先掌握选择器把范围选准,理解 Counter 与 Gauge 的区别,熟练使用 rate()、聚合和除法,再会用 histogram_quantile() 看延迟分位数,已经能覆盖绝大多数基础设施与应用监控查询。
真正要养成的习惯是:每个模板都先在 Explore 里验证指标、标签和单位,再放进面板或告警。模板负责让你快速开始,理解数据类型和标签维度,才是避免“图画出来了,但结论是错的”的关键。