3304 字
17 分钟
监控与可观测性:PromQL 实战手册——先抄模板,再理解语法

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]) * 300

irate() 同样计算每秒速率,但只取最后两个样本,反应更灵敏,噪声也更大。看长期趋势、做告警,优先用 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 便于定位是哪块盘忙。
磁盘 IOPSsum 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 里验证指标、标签和单位,再放进面板或告警。模板负责让你快速开始,理解数据类型和标签维度,才是避免“图画出来了,但结论是错的”的关键。

监控与可观测性:PromQL 实战手册——先抄模板,再理解语法
https://www.anexns.cloudns.org/posts/monitoring-promql/
作者
Anexns
发布于
2026-11-16
许可协议
CC BY-NC-SA 4.0