4.PromQL

promQL数据类型

即时向量（Instant Vector）：特定或全部的时间序列集合上，具有相同时间戳的一组样本值称为即时向量
范围向量（RangeVector）：特定或全部的时间序列集合上，在指定的同一时间范围内的所有样本
标量（Scalar）：一个浮点型的数据值
字符串（String）：支持使用单引号、双引号或反引号进行引用，但反引号中不会对转义字符进行转义

时间序列选择器

即时向量选择器
区间向量选择器

即时向量选择器

* 由两部分构成
指标名称：用于指定指标名称（可选）
标签选择器：用于过滤标签，写在{}中（可选）

* 写法说明
· 仅给定指标名称，或在标签名称上使用了空值的标签匹配模式：返回给定指标下的所有时间序列的即时样本。
  例如，prometheus_http_requests_total和prometheus_http_requests_total{}的效果相同

· 仅给定标签匹配模式：返回所有符合给定的匹配器的所有时间序列的即时样本。
  {job=~".*"}表达式，是不合法的。
  {job=~".+"}和{job=~".*", method="get"}表达式是合法的，因为它们都有一个与空标签值不匹配的选择器。

· 同时给定指标名称和标签匹配模式：返回给定的指标下的，且符合给定的标签过滤器的所有时间序列上的即时样本。
  例如，prometheus_http_requests_total{code="200"}

* 相同的标签可以有多个匹配模式
node_filesystem_size_bytes{job="node”, mountpoint=~"/run/.*”, mountpoint!~"/run/user/.*"}

* 标签匹配运算符
=    相等匹配，例如：job="mysql"
!=   反向匹配
=～   正则表达式匹配，例如：job=~"node_.*" 或 job=~".*_exporter"
!～   正则表达式的反向匹配

区间向量选择器

* 定义区间向量选择器
·和即时向量选择器大致相同，唯一不同之处在于需要在表达式后面使用一个时间值（使用方括号[]括起来），表示获取指定时间范围内的所有指标。
·PromQL的区间向量选择器支持的时间单位有：s（秒）、m（分钟）、h（小时）、d（天）、w（周）、y（年）。
·必须使用整数时间，可以将多个不同级别的时间单位组合起来，时间单位要由大到小。例如1h30m，不能使用1.5h。

* 区间向量表达式举例
process_resident_memory_bytes{job="prometheus"} [15m]”

偏移量修改器

* 默认情况下，即时向量选择器和区间向量选择器都以当前时间为基准时间点，而偏移量修改器（Offset modifier）能够修改该基准时间点。
  · 偏移量修改器的使用方法是在选择器表达式之后使用“offset”关键字指定要偏移的时间。

# 即时向量表达式，选择当前最新的数据
process_resident_memory_bytes{job="prometheus”}

# 区间向量表达式，选择以当前时间为基准的15分钟内的数据
process_resident_memory_bytes{job="prometheus"} [15m]

#获取1小时以前的即时向量和区间向量（使用offset关键字）
process_resident_memory_bytes{ job="prometheus"} offset 1h
process_resident_memory_bytes{ job="prometheus"} [15m] offset 1h

* 实际应用举例
# 给出prometheus在过去一小时内内存使用量的变化
process_resident_memory_bytes{ job="prometheus"}-process_resident_memory_bytes{ job="prometheus"}offset 1h
# 同样的操作方法也适用于区间向量
rate(process_resident_memory_bytes{ job="prometheus"} [15m])-rate(process_resident_memory_bytes{ job="prometheus"} [15m]offset 1h)”

聚合操作

Prometheus为使用者提供了内置的聚合操作符，这些聚合操作符仅仅适用于对单个即时向量进行聚合操作

* 语法
# 两者的效果相同
<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]
<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)

* 分组聚合：先分组、后聚合
    * by关键字使用列出的标签进行分组。
    * without关键字使用未列出的标签进行分组。即先删除列出的标签，在使用剩余的标签进行分组。

* promQL聚合操作符
·sum()：对样本值求和
·avg()：对样本值求平均值
·count()：统计分组内时间序列的数量
·min()：取样本值中的最小值
·max()：取样本值中的最大值
·stddev()：对样本值求标准差，以帮助用户了解数据的波动大小。例如，作业中的一个实例具有与平均值相差几个标准差的度量标准，说明这一实例有问题
·stdvar()：对样本值求方差，是标准差的平方，用于统计
·bottomk()：对样本进行排序，返回当前样本值后n位时间序列
·topk()：与bottomk相反，返回样本值前n位的时间序列。例如：返回http请求数前5位的时间序列值，topk(5,http_requests_total)
·quantile()：分位数用于评估数据的分布状态，该函数会返回分组内指定的分位数的值，即数值落在小于等于指定的分为区间的比例。用于计算当前样本数数值的分布情况：quantite(ø,express)。其中，0<=ø<=1。例如，当ø=0.5时，用来表示找到以下样本数据中的中位数：·quantile(ø.http_requests_total)
·count_values()：对相同的value计数，用于统计时间序列中每一个样本指中出现的次数

* parameter：为可选参数，聚合的参数。
  
* 举例
指标prometheus_http_requests_total由code、handler、instance和job的标签组成的时间序列数据，则可以通过sum操作符进行如下计算，统计不同请求响应码的数量：
# 两个表达式的效果是相同的
sum(prometheus_http_requests_total) by (code)
sum(prometheus_http_requests_total) without (handler, instance, job)

其他函数

rate()函数用来计算一定范围内时间序列的每秒平均增长率， 只能与计数器一起使用
irate()函数用于计算范围向量中时间序列增加的每秒即时速率

算数运算符

* 算术运算符有6种：
    * +（加）、-（减）、*（乘）、/（除） 、%（取模）和^（幂运算）

* 算术运算操作符支持三类操作：
    * scalar/scalar（标量/标量）之间的操作
        * 在两个标量之间进行算术运算，得到的结果还是标量。
    * vector/scalar（即时向量/标量）之间的操作
        * 即时向量与标量之间进行算术运算时，会使用算术运算符将标量依次作用于即时向量中的每一个样本值，从而得到一组新的时间序列（返回值不带指标名）
    * vector/vector（即时向量/即时向量）之间的操作
        * 对两个即时向量进行运算的方法，见下面的向量匹配。

关系运算符

* 关系运算符有6种：
    * ==（相等）、!=（不相等）、>（大于）、<（小于）、>=（大于等于）和<=（小于等于）

* 默认情况下，关系运算符用于对时序数据进行过滤。但是在有些情况下，可以通过在关系运算符之后使用bool修饰符，从而不对时间序列进行过滤，而是直接返回0（false）或者1（true）。

* 关系运算操作符支持三类操作：
    * scalar/scalar（标量/标量）之间的操作
        * 在两个标量之间进行关系运算，必须使用bool修饰符（如图5-9），得到的结果还是标量，即0（false）或者1（true）。
    * vector/scalar（即时向量/标量）之间的操作
        * 即时向量与标量之间进行关系运算时，会使用关系运算符将标量依次作用于即时向量中的每一个样本值，如果样本值与这个标量的比较结果是false，则这个时间序列数据被丢弃，如果是true，则这个时间序列数据被保留在结果中。（如图5-10）
    * vector/vector（即时向量/即时向量）之间的操作
        * 即时向量与即时向量之间进行关系运算时，运算符默认情况下是过滤的，用于匹配条目。表达式不是true或在表达式的另一侧找不到匹配项的向量元素将被从结果中删除，即不在结果中显示；否则将保留左侧的度量指标和标签的样本数据写入即时向量。如果提供了bool修饰符，则删除的向量元素的值为0，而保留的向量元素的值为1，左侧标签值为1。

向量匹配

* 在两个即时向量之间使用运算符时，哪些样本应该适用于哪些其他样本？这种即时向量的匹配称为向量匹配。

* Prometheus提供了两种基本的向量匹配模式：
    * one-to-one向量匹配
    * many-to-one（one-to-many）向量匹配

1、一对一向量匹配模式
* 一对一向量匹配模式（one-to-one）：
    * 从运算符的两边表达式中获取即时向量，依次比较并找到唯一匹配（标签和对应值完全一致）的一对样本值。
    * 不能匹配的时间序列不会出现在结果中。

* 一般默认（具有标签完全一致的时间序列）的表达式格式是：
vector1 <operator> vector2

* 如果运算符两侧表达式标签不一致，可以使用关键字on或ignoring修改标签间的匹配行为。表达格式分别为：
//on：只使用指定的标签进行匹配
<vector expr> <bin-op> on(<label list>) <vector expr>
//ignoring：忽略指定的标签进行匹配
<vector expr> <bin-op> ignoring(<label list>) <vector expr>

示例：
//数据样本
method_code:http_errors:rate5m{method="get", code="500"}  24
method_code:http_errors:rate5m{method="get", code="404"}  30
method_code:http_errors:rate5m{method="put", code="501"}  3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21
method:http_requests:rate5m{method="get"}  600
method:http_requests:rate5m{method="del"}  34
method:http_requests:rate5m{method="post"} 120

//（一对一向量匹配模式）先筛选出第一个指标中的code="500"，然后再忽略标签code，最后进行一对一向量匹配
method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

//计算后的结果
{method="get"}  0.04            #  24 / 600  
{method="post"} 0.05            #  6 / 120

2、多对一和一对多的匹配模式
* 多对一和一对多的匹配模式（many-to-one and one-to-many）：
    * “一”侧的每个元素，可与“多”侧的多个元素进行匹配。
    * 必须使用group_left或group_right明确指定哪侧为“多”侧。

“多”侧的表达式如下：
<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>

示例：
//数据样本
method_code:http_errors:rate5m{method="get", code="500"}  24
method_code:http_errors:rate5m{method="get", code="404"}  30
method_code:http_errors:rate5m{method="put", code="501"}  3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21
method:http_requests:rate5m{method="get"}  600
method:http_requests:rate5m{method="del"}  34
method:http_requests:rate5m{method="post"} 120

//左侧向量对每个方法标签值包含多个条目。因此，使用group_left来表示这一点。
method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

//计算后的结果
{method="get", code="500"}  0.04            #  24 / 600  
{method="get", code="404"}  0.05            #  30 / 600  
{method="post", code="500"} 0.05            #   6 / 120  
{method="post", code="404"} 0.175           #  21 / 120  

逻辑运算符

* 逻辑运算符有三种：
    * and、or和unless
* 逻辑运算符仅用于向量与向量之间。所有逻辑运算符都以多对多的方式工作，它们是唯一能工作于多对多方式的运算符。
    * 不同于算术运算符和比较运算符，因为没有执行任何数学计算，所以重点是描述一个组是否包含样本。

//and逻辑运算会产生一个由vector1的元素组成的新的向量。该向量包含vector1中完全匹配vector2中的元素。
vector1 and vector2
//or逻辑运算会产生一个新的向量，该向量包含vector1的所有原始元素（标签集+值）的向量，以及vector2中没有与vector1匹配标签集的所有元素。
vector1 or vector2
//unless逻辑运算会产生一个由vector1的元素组成的向量，而这些元素在vector2中没有与标签集完全匹配的元素，两个向量中的所有匹配元素都被删除。
vector1 unless vector2

运算符优先级

Prometheus运算符的优先级，由高到低的：
    * ^
    * *、/、%
    * +、-
    * ==、!=、<、>、<=、>=
    * and、unless
    * or

prometheus函数

* Prometheus提供了多种功能的函数供用户使用，包括数学函数、时间函数、标签操作函数、Counter指标增长率计算函数等。
* 说明文档：https://prometheus.io/docs/prometheus/latest/querying/functions/#label_replace

* 数学函数
* 数学函数对即时向量执行标准的数学运算，如计算绝对值或取对数。即时向量中的每个样本都是独立处理的，并且返回值没有指标名。
1、abs()
* 该函数返回即时向量中值的绝对值。

示例：
//process_open_fds表达式，结果返回
process_open_fds{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    10
process_open_fds{instance="localhost:9090", job="prometheus"}                       37
//process_open_fds - 100表达式，结果返回
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    -91
{instance="localhost:9090", job="prometheus"}                       -64
//abs(process_open_fds - 100)表达式，结果返回
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}     91
{instance="localhost:9090", job="prometheus"}                        64

2、sqrt()
* 该函数返回即时向量中值的平方根。

示例：
//process_open_fds表达式，结果返回
process_open_fds{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    9
process_open_fds{instance="localhost:9090", job="prometheus"}                       36
//sqrt(process_open_fds)表达式，结果返回
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    3
{instance="localhost:9090", job="prometheus"}                       6

3、round()
* 该函数将即时向量中的值四舍五入到最近的整数。

4、clamp_max()和clamp_min()
* clamp_max()：该函数返回小于指定值的即时向量。
* clamp_minx()：该函数返回大于指定值的即时向量。

示例：
//process_open_fds表达式，结果返回
process_open_fds{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    9
process_open_fds{instance="localhost:9090", job="prometheus"}                       36

//查找进程打开文件描述符数量小于78的表达式为clamp_min(process_open_fds, 33)
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    9
{instance="localhost:9090", job="prometheus"}                       33

//查找进程打开文件描述符数量大于33的表达式为clamp_min(process_open_fds, 33)
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    33
{instance="localhost:9090", job="prometheus"}                       36

5.2、时间函数
* Prometheus使用的是协调世界时（UTC），没有时区的概念。为了使用户在使用中不用自己实现与日期相关的逻辑，Prometheus提供了一些时间函数。
1、time()
* 返回自UTC 1970年1月1日以来的秒数。

示例：
//查看进程运行了多长时间的表达式time() - process_start_time_seconds
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    263824.1900000572
{instance="localhost:9090", job="prometheus"}                       186246.50999999046

2、时钟和日历类函数
* year()：返回给定时间的年份
* month()：返回给定时间的月份。返回值为1~12
* day_of_month()：返回给定时间是几号（一个月的第几天的值），返回值为1~31
* hour()：返回给定时间的小时，返回值0~23
* minute()：返回给定时间的分钟，返回值为0~59
* days_in_month()：返回给定时间的月份的天数，返回值为28~31
* day_of_week()：返回给定时间是星期几，返回值为0~6，其中0表示星期日

示例：
//返回年份  year(process_start_time_seconds)
{instance="localhost:9090", job="prometheus"}    2022
//返回是几月  month(process_start_time_seconds)
{instance="localhost:9090", job="prometheus"}    10
//返回是几号
day_of_month(process_start_time_seconds)
{instance="localhost:9090", job="prometheus"}    14

5.3、标签操作函数
1、label_replace()
* 该函数的格式如下：
label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)
    
·对即时向量v中的每个时间序列进行处理，根据标签src_label的值匹配正则表达式regex。
·如果匹配，标签dst_label的值会替换成replacement string的值（replacement string可以使用正则表达式的捕获组，用1、2等引用），最终返回的新的时间序列中会包括替换后的标签以及输入中的原始标签。
·如果正则表达式不匹配，则返回原来的时间序列。

示例：
//up表达式，结果返回
up{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    1
up{instance="localhost:9090", job="prometheus"}                       1

//label_replace(up, "host", "$1", "instance", "(.*):.*")表达式，结果返回
up{host="10.1.1.13”, env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    1
up{host="localhost", instance="localhost:9090", job="prometheus"}                       1

2、label_join()
* 该函数的格式如下：
label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)

·对于v中的每个时间序列，使用分隔符（separator）连接所有src_label的所有值，该值保存在标签dst_label中，最终返回新的时间序列中包含dst_label标签和原有标签
·这个函数中可以有任意数量的src_label。

示例：
//up表达式，结果返回
up{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    1
up{instance="localhost:9090", job="prometheus"}                       1

//label_join(up, "host", "_", "instance", "job")表达式，结果返回
up{host="10.1.1.13:9100_node”, env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    1
up{host="localhost:9090_prometheus", instance="localhost:9090", job="prometheus"}                 1

5.4、Counter指标增长率
1、increase()
* 该函数的格式如下：
increase(v range-vector)

* 只能与计数器类型的指标一起使用，用于计算区间向量中时间序列的增量。它获取区间向量中的第一个和最后一个样本，并返回其增长量。

示例：
* 指标process_cpu_seconds_total（用户和系统CPU总时间，均以秒为单位）是counter类型，通过process_cpu_seconds_total[3m]获取时间序列最近3分钟的所有样本，increase计算出最近3分钟的增长量，最后除以时间180秒得到process_cpu_seconds_total样本在最近3分钟的平均增长率。

//increase(process_cpu_seconds_total[3m]) / 180表达式，结果返回
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    0.0056363636363640215
{instance="localhost:9090", job="prometheus"}                       0.0008484848484847658

2、rate()
* 该函数的格式如下：
rate(v range-vector)

* 只能与计数器类型的指标一起使用，用于计算区间向量中时间序列的每秒平均增长率。当因目标重启而导致计数器重置时，会自动调整。它是在实际工作中使用PromQL时的主要函数，最适用于告警和缓慢移动计数器的图形。

示例：
//process_cpu_seconds_total样本在最近3分钟的平均增长率的表达式rate(process_cpu_seconds_total[3m])
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    0.006000000000000055
{instance="localhost:9090", job="prometheus"}                       0.0007272727272727548

3、irate()
* 该函数的格式如下：
irate(v range-vector)

* 计算区间向量中时间序列的每秒即时增长率，是一个灵敏度更高的函数。当因目标重启而导致计数器重置时，会自动调整。
* irate函数是通过区间向量中最后两个数据点来计算区间向量的增长速率，反映的是即时增长率，绘制出的图形可以更好地反映样本数据的即时变化状态。
* 由于irate函数相比于rate函数灵敏度更高，在需要分析长期趋势或者告警规则的场景中，irate的这种灵敏度会容易形成干扰，所以在长期趋势分析或者告警中建议使用rate函数。

示例：
//irate(process_cpu_seconds_total[3m])表达式，结果返回
{env="dev_node_exporter", instance="10.1.1.13:9100", job="node"}    0.007330889703425521
{instance="localhost:9090", job="prometheus"}                       0.0006666666666670077

5.5、Gauge指标趋势变化预测
1、predict_linear()
* 该函数的格式如下：
predict_linear(v range-vector, t scalar)

* 基于区间向量，使用简单的线性回归预测时间序列 t 秒的值，从而可以对时间序列的变化趋势做出预测。
* 在传统监控环境中，管理员可以对资源使用最高值设定阈值，只要资源使用达到或超过该阈值，告警通知管理员进行人工问题处理。但是对于突发式增长类业务，或因不可预知的程序bug而造成主机或云资源使用暴涨时，传统监控告警机制中，管理员或对应业务人员收到告警后，可能已经无法进行问题处理了，此时系统已经是宕机状态了。这种场景刚好适合使用本节介绍的predict_linear函数，通过设定合理的时间范围，对资源消耗趋势做出预测。

示例：
* 根据过去1小时的样本数据，预测主机的可用磁盘空间是否在4小时内被占满。
predict_linear(node_filesystem_free_bytes{mountpoint="/"} [1h], 4 * 3600) < 0