PromQL 语法

什么是 PromQL 

PromQL (Prometheus Query Language) 是 Prometheus 监控系统中用于查询时间序列数据的语言。它允许用户编写查询，以从 Prometheus 中检索并处理监控数据。

PromQL 的基础概念

1. 时间序列

Prometheus 中的时间序列由以下几个部分组成：

• 指标名称 (Metric name)：表示时间序列的类别。例如，http_requests_total 表示 HTTP 请求的总数。
• 标签 (Labels)：用于标识某个时间序列的具体特性。例如，method="GET", status="200" 可以标识不同的 HTTP 方法和状态。
• 时间戳 (Timestamp)：表示记录数据的具体时间。
• 值 (Value)：时间序列在某一时间点上的具体数值。

2. 基本查询

基本的 PromQL 查询是通过 指标名称来检索 时间序列数据。

示例：

# 这将返回 http_requests_total 指标的所有时间序列。
http_requests_total

3. 标签过滤

可以通过标签来筛选时间序列。使用 {} 来包含标签选择器：

示例：

# 该查询返回所有符合 method="GET" 且 status="200" 的时间序列。
http_requests_total{method="GET", status="200"}

可以通过 =, !=, =~, !~ 等操作符来进行更多的匹配规则：

符号	含义
=	精确匹配
!=	不匹配
=~	正则表达式匹配
!~	正则表达式不匹配

4. 区间选择

PromQL 支持通过时间区间来查询过去一段时间的数据，称为 区间向量 (Range Vector)。

示例：

# 该查询表示从当前时间起过去 5 分钟内的数据。
http_requests_total[5m]

---

PromQL 的数据类型

PromQL 中有四种数据类型：

• 瞬时向量 (Instant Vector)：一组带有当前时间戳的时间序列。
• 区间向量 (Range Vector)：一组带有时间区间的时间序列。
• 标量 (Scalar)：单个浮点数值。
• 字符串 (String)：单个字符串值（较少使用）。

1. 瞬时向量

示例：

# 返回 up 指标的所有瞬时向量
up

2. 区间向量

示例：

# 返回 up 指标在过去 5 分钟内的所有时间序列。
up[5m]

3. 标量

标量是单个数值，通常用于某些计算场景。

示例：

# 表示常量 5。
5

---

PromQL 的操作符

1. 算术运算符

PromQL 支持常见的算术运算符，主要用于对查询结果进行计算。

操作符	含义
+	加
-	减
*	乘
/	除
%	取余
^	幂运算

示例：

# 将请求速率结果乘以 100。
rate(http_requests_total[5m]) * 100

---

2. 比较运算符

用于对查询结果进行比较操作。

操作符	含义
==	等于
!=	不等于
>	大于
<	小于
>=	大于等于
<=	小于等于

示例：

# 返回所有状态为 1 的实例（表示健康）
up == 1

---

3. 逻辑运算符

用于对不同查询结果进行逻辑运算。

操作符	含义
and	交集
or	并集
unless	差集

示例：

# 返回所有健康且请求数大于 100 的实例。
up == 1 and http_requests_total > 100

---

PromQL 的聚合操作符

Prometheus 提供了丰富的聚合操作符，用于将多条时间序列合并为一条。

操作符	含义
sum	求和
avg	平均值
min	最小值
max	最大值
count	计数
stddev	标准差
stdvar	方差
topk	取前 k 大
bottomk	取前 k 小
quantile	分位数

示例：

# 计算过去 5 分钟内所有请求的总和。
sum(rate(http_requests_total[5m]))

# 按 instance 标签计算请求速率的平均值。
avg by (instance) (rate(http_requests_total[5m]))

---

PromQL 的内置函数

PromQL 提供了一些内置函数，帮助用户对时间序列进行更复杂的计算。

1. 时间序列计算函数

rate()：计算时间序列在某段时间内的速率（适用于 Counter 类型）

rate(http_requests_total[5m])

irate()：计算时间序列的瞬时速率。

irate(http_requests_total[1m])

increase()：计算某个区间内指标值的增量（适用于 Counter 类型）。

increase(http_requests_total[5m])

---

2. 统计函数

avg_over_time()：计算时间区间内的平均值。

avg_over_time(http_requests_total[10m])

sum_over_time()：计算时间区间内的总和。

sum_over_time(http_requests_total[10m])

max_over_time()：计算时间区间内的最大值。

max_over_time(http_requests_total[10m])

---

3. 特殊函数

abs()：返回绝对值。

abs(node_load1)

clamp_min() 和 clamp_max()：限制最小值和最大值。

clamp_min(cpu_usage, 0.1)

---

4. 偏移数据

offset：来查询指定时间之前的数据。它允许你向前或向后偏移数据的时间点。

# 表示查询 1 小时前的数据。
rate(http_requests_total[5m] offset 1h)

---

PromQL 的子查询

子查询 (Subquery) 是一种强大的功能，允许你在指定时间范围内查询一组区间向量 (Range Vector)，然后将结果用作进一步的操作。这与普通的区间向量查询不同，子查询在区间上执行某个操作，然后将结果作为新的时间序列。子查询的语法是在查询的基础上添加 []。

语法：

<查询>[<区间>:<解析度>]

<查询>：你要执行的基本查询。
<区间>：子查询的时间范围，表示从当前时间点向过去的时间范围。
<解析度>（可选）：用于控制子查询的采样分辨率（时间间隔），默认为 Prometheus 的全局评估间隔。

示例：

avg_over_time(rate(http_requests_total[5m])[30m:])# rate(http_requests_total[5m])：首先计算过去 5 分钟的请求速率。
# [30m:]：接下来，我们对过去 30 分钟内的请求速率进行子查询，生成一个时间区间数据。
# avg_over_time()：最后，对这些请求速率计算出 30 分钟内的平均值。

# 该查询表示：对过去 1 小时内的请求速率数据进行采样，每 1 分钟取一次样本，然后计算这些样本的平均值。
avg_over_time(rate(http_requests_total[5m])[1h:1m])# rate(http_requests_total[5m])：计算 5 分钟的请求速率。
# [1h:1m]：查询过去 1 小时的数据，并每 1 分钟取一次样本。
# avg_over_time()：对这些样本计算 1 小时内的平均值。

# 计算过去 1 小时内每 5 分钟请求速率的总和。
sum_over_time(rate(http_requests_total[5m])[1h:])

# 每 10 秒钟采样一次，并返回过去 1 小时内的请求速率数据。
rate(http_requests_total[5m])[1h:10s]

# 首先计算 5 分钟的请求速率，然后在过去 1 小时内查找最大请求速率。
max_over_time(rate(http_requests_total[5m])[1h:])