PromQL 入门

查询时间序列

• 直接使用监控指标名称查询时，可以查询该指标下的所有时间序列。

• PromQL 还支持用户根据时间序列的标签匹配模式来对时间序列进行过滤，目前主要支持两种匹配模式：完全匹配和正则匹配。

  • 完全匹配：PromQL 支持使用=和!=两种完全匹配模式：

    • 通过使用label=value可以选择那些标签满足表达式定义的时间序列；

    • 使用label!=value则可以根据标签匹配排除时间序列；

  • 正则匹配：

    • 使用label=~regx表示选择那些标签符合正则表达式定义的时间序列；

    • 使用label!~regx进行排除；

  多个表达式之间使用|进行分离。

范围查询

直接通过类似于 PromQL 表达式http_requests_total查询时间序列时，返回值中只会包含该时间序列中的最新的一个样本值，这样的返回结果我们称之为瞬时向量，并这样的表达式称之为瞬时向量表达式。

如果想获取过去一段时间范围内的样本数据，则需要使用区间向量表达式。区间向量表达式和瞬时向量表达式之间的差异在于在区间向量表达式中需要定义时间选择的范围，时间范围通过时间范围选择器[]进行定义。通过区间向量表达式查询到的结果我们称为区间向量。

例如，通过以下表达式可以选择最近 5 分钟内的所有样本数据：

http_requests_total{}[5m]

PromQL 的时间范围选择器支持的时间单位如下：

• s - 秒

• m - 分钟

• h - 小时

• d - 天

• w - 周

• y - 年

时间位移操作

在瞬时向量表达式或者区间向量表达式中，都是以当前时间为基准：

http_request_total{}     # 瞬时向量表达式，选择当前最新的数据
http_request_total{}[5m] # 区间向量表达式，选择以当前时间为基准，5分钟内的数据

如果想查询，5 分钟前的瞬时样本数据，或昨天一天某个区间内的样本数据呢? 这个时候可以使用位移操作，位移操作的关键字为 offset。

http_request_total{} offset 5m
http_request_total{}[1d] offset 1d

聚合操作

一般来说，如果在描述样本特征的标签（label）并非唯一的情况下，通过 PromQL 查询数据，会返回多条满足这些特征维度的时间序列。PromQL 提供的聚合操作可以用来对这些时间序列进行处理，形成一条新的时间序列：

# 查询系统所有 http 请求的总量
sum(http_request_total)

# 按照 mode 计算主机 CPU 的平均使用时间
avg(node_cpu) by (mode)

# 按照主机查询各个主机的 CPU 使用率
sum(sum(irate(node_cpu{mode!='idle'}[5m])) / sum(irate(node_cpu[5m]))) by (instance)

标量

标量只有一个数字，没有时序。

例如：

10

需要注意的是，当使用表达式 count(http_requests_total)，返回结果的数据类型依然是瞬时向量。用户可以通过内置函数 scalar() 将单个瞬时向量转换为标量。

字符串

直接使用字符串，作为 PromQL 表达式，则会直接返回字符串。

"this is a string"
'these are unescaped: \n \\ \t'
`these are not unescaped: \n ' " \t`

合法的 PromQL 表达式

所有的 PromQL 表达式都必须至少包含一个指标名称（http_request_total），或者一个不会匹配到空字符串的标签过滤器（例如 {code="200"}）。

除了使用<metric name>{label=value}的形式以外，还可以使用内置的__name__标签来指定监控指标名称：

{__name__=~"http_request_total"}                             # 合法
{__name__=~"node_disk_bytes_read|node_disk_bytes_written"}   # 合法