PromQL语法说明
前提
- 如果不了解PromQL查询语言，请到官网查看https://prometheus.io/docs/prometheus/latest/querying/basics/
- 了解bonree对指标类型的划分以及指标支持的聚合方式。
注意
由于Prometheus指标的存储方式与bonree指标不同，因此PromQL语法做出以下修改：
1.在instant查询上，不支持查bonree的frm和自定义类型指标以及没有last聚合方式的指标。
说明：instant vector语义是瞬时向量，取每个时间序列最近5min的最新值。bonree在指标存储是对指标按照时间粒度做了预聚合，所存储上该指标只有支持last(最新值)聚合方式才能使用。
2. range vector不支持明细数据查询，改为基于当前时间范围粒度，按照指标的默认聚合方式计算。
说明：range vector语义是时间范围内上报的明细数据。bonree在指标上使用了预聚合方式，按照时间粒度进行预先汇总。基于性能考虑，当时间范围很长时，range vector会按照查询的粒度表并使用指标的默认聚合方式计算，导致无法获取最小粒度的明细数据。
3. <aggregation>_over_time()函数基于range vector数据做聚合计算，函数能否使用取决于该指标是否有对应的聚合方式。
说明：agg_over_time函数（除stddev_over_time和stdvar_over_time外）用来对range_vector的明细数据进行聚合计算。如果指标不支持该聚合方式，会导致查询失败。
4. 建议尽量使用PromQL查询Prometheus接入的指标数据。
查询方式
- 与Prometheus一样，支持instant和range两种查询方式。
- range查询不支持自定义step，内部有默认实现规则（看下文）
粒度
查询指标数据时，根据不同的时间范围，按照不同的时间粒度点聚合计算指标。
- range查询
| 时间范围 | 粒度 |
|---|---|
| ≤30min | 15s |
| ≤3h | 1min |
| ≤24h | 10min |
| ≤7d | 1hour |
| ≤14d | 6hour |
| >14d | 1d |
PromQL语法支持清单
（基于Prometheus2.53版本，https://prometheus.io/docs/prometheus/latest/querying/basics/）
| 类别 | 名称 |
|---|---|
| 基本数据类型 | instant vector：瞬时向量 |
| range vector：区间向量 | |
| literals：数字和字符串常量 | |
| 选择器 | · =：与字符串匹配 |
· !=：与字符串不匹 | |
· =~：与正则匹配 | |
· !~：与正则不匹配 | |
| 时间选择 | @ : 指定评估时间，如：http_requests_total @ 1609746000 |
| offset:指定偏移时间，如：http_requests_total offset 1m (range query不支持保持原时间) | |
| duration: 指定范围时间，如：http_requests_total[1m] | |
| Subquery | 不支持 |
| 算术运算 | 支持：+ (加) - ：(减) * ：(乘) - / ：(除) % ：(取余) ^ ：(求幂) |
| 比较运算 | · 支持：== (相等) != (不相等) >(大于) < (小于) ≥ (大于等于) ≤ (小于等于)· 两个scalars之间不支持操作· 不支持使用bool关键字 |
| 集合运算 | 不支持 and or unless |
| 集合匹配 | 不支持 group_left/group_right on/ignoring |
| 聚合函数 | · sum（计算维度总和） |
· min（选择最小尺寸） | |
· max（选择最大尺寸） | |
· avg（计算各个维度的平均值） | |
· stddev（计算维度上的总体标准差） | |
· stdvar（计算各维度的总体标准方差） | |
· count（计算向量中元素的数量） | |
· bottomk（按样本值最小的 k 个元素） | |
· topk（按样本值最大的 k 个元素） | |
| 函数<aggregation>_over_time() | · avg_over_time(range-vector)：指定区间内所有点的平均值。 |
· min_over_time(range-vector)：指定区间内所有点的最小值。 | |
· max_over_time(range-vector)：指定区间内所有点的最大值。 | |
· sum_over_time(range-vector)：指定区间内所有值的总和。 | |
· count_over_time(range-vector)：指定区间内所有值的计数。 | |
· quantile_over_time(scalar, range-vector)：指定区间内的值的 φ 分位数（0 ≤ φ ≤ 1）。 | |
· stddev_over_time(range-vector)：指定区间内值的总体标准差。 | |
· stdvar_over_time(range-vector)：指定区间内值的总体标准方差。 | |
· last_over_time(range-vector)：指定间隔内最近的点值。 | |
| 三角函数 | · acos(v instant-vector)：计算所有元素的反余弦v |
· acosh(v instant-vector)：计算所有元素的反双曲余弦v | |
· asin(v instant-vector)：计算所有元素的反正弦v | |
· asinh(v instant-vector)：计算所有元素的反双曲正弦v | |
· atan(v instant-vector)：计算所有元素的反正切v | |
· atanh(v instant-vector)：计算所有元素的反双曲正切v | |
· cos(v instant-vector)：计算所有元素的余弦v | |
· cosh(v instant-vector)：计算所有元素的双曲余弦v | |
· sin(v instant-vector)：计算所有元素的正弦v | |
· sinh(v instant-vector)：计算所有元素的双曲正弦v | |
· tan(v instant-vector)：计算所有元素的正切v | |
· tanh(v instant-vector)：计算所有元素的双曲正切v | |
| 函数 | · abs(v instant-vector)：返回输入向量，其中所有样本值均转换为其绝对值。 |
· ceil(v instant-vector)：将所有元素的样本值四舍五入v为最接近的整数 | |
· changes(v range-vector)：对于每个输入时间序列，以瞬时向量形式返回其值在指定时间范围内发生变化的次数 | |
· delta(v range-vector)：计算范围向量中每个时间序列元素的第一个值和最后一个值之间的差值v，返回具有给定增量和等效标签的瞬时向量。增量被推断为覆盖范围向量选择器中指定的整个时间范围，因此即使样本值都是整数，也有可能得到非整数结果。 | |
| · 导数。范围向量必须至少有两个样本才能执行计算。当在范围向量中找到+Inf或 时-Inf，计算出的斜率和偏移值将为NaN | |
· deriv(v range-vector)：v使用简单线性回归计算范围向量中时间序列的每秒导数。范围向量必须至少有两个样本才能执行计算。当在范围向量中找到+Inf或 时-Inf，计算出的斜率和偏移值将为NaN | |
· exp(v instant-vector)：计算 中所有元素的指数函数v | |
· floor(v instant-vector)：将所有元素的样本值向下舍入v为最接近的整数。 | |
· holt_winters：(v range-vector, sf scalar, tf scalar)根据 的范围生成时间序列的平滑值v。平滑因子 越低sf，旧数据越重要。趋势因子 越高tf，数据中的趋势考虑得越多。sf和都tf必须介于 0 和 1 之间。 | |
· idelta(v range-vector)：计算范围向量中最后两个样本之间的差异v，返回具有给定增量和等效标签的瞬时向量。 | |
· increase(v range-vector)：计算范围向量中时间序列的增量。 | |
· irate(v range-vector)：计算范围向量中时间序列的每秒瞬时增长率 | |
· ln(v instant-vector)：计算 中所有元素的自然对数v | |
· log2(v instant-vector)：计算 中所有元素的二进制对数v | |
· log10(v instant-vector)：计算 中所有元素的十进制对数v | |
· predict_linear(v range-vector, t scalar)：t根据范围向量v，使用简单线性回归预测从现在开始的时间序列秒的值 。 | |
· rate(v range-vector)：计算范围向量中时间序列的每秒平均增长率。 | |
· resets(v range-vector)：对于每个输入时间序列，以瞬时向量的形式返回在指定时间范围内计数器重置的次数。 | |
· round(v instant-vector, to_nearest=1 scalar)：将所有元素的样本值四舍五入v为最接近的整数。如果出现平局，则向上舍入。 | |
· scalar(v instant-vector)：给定一个单元素输入向量，返回该单元素的样本值作为标量。如果输入向量不只有一个元素，scalar则返回NaN | |
· sgn(v instant-vector)：返回一个向量，其中所有样本值都转换为其符号，定义如下：如果 v 为正，则为 1；如果 v 为负，则为 -1；如果 v 等于零，则为 0。 | |
· sort(v instant-vector)：返回按样本值升序排序的向量元素。原生直方图按其观测值总和排序。 | |
· sort_desc()：与 相同sort，但按降序排序。 | |
· sqrt(v instant-vector)：计算 中所有元素的平方根v。 | |
· min_over_time(range-vector)：指定区间内所有点的最小值。 | |
· max_over_time(range-vector)：指定区间内所有点的最大值。 | |
· sum_over_time(range-vector)：指定区间内所有值的总和。 | |
· count_over_time(range-vector)：指定区间内所有值的计数。 | |
· quantile_over_time(scalar, range-vector)：指定区间内的值的 φ 分位数（0 ≤ φ ≤ 1）。 | |
· stddev_over_time(range-vector)：指定区间内值的总体标准差。 | |
· stdvar_over_time(range-vector)：指定区间内值的总体标准方差。 | |
· last_over_time(range-vector)：指定间隔内最近的点值。 | |
| 三角函数 | · acos(v instant-vector)：计算所有元素的反余弦v |
· acosh(v instant-vector)：计算所有元素的反双曲余弦v | |
· asin(v instant-vector)：计算所有元素的反正弦v | |
· asinh(v instant-vector)：计算所有元素的反双曲正弦v | |
· atan(v instant-vector)：计算所有元素的反正切v | |
· atanh(v instant-vector)：计算所有元素的反双曲正切v | |
· cos(v instant-vector)：计算所有元素的余弦v | |
· cosh(v instant-vector)：计算所有元素的双曲余弦v | |
· sin(v instant-vector)：计算所有元素的正弦v | |
· sinh(v instant-vector)：计算所有元素的双曲正弦v | |
· tan(v instant-vector)：计算所有元素的正切v | |
· tanh(v instant-vector)：计算所有元素的双曲正切v | |
| 函数 | · abs(v instant-vector)：返回输入向量，其中所有样本值均转换为其绝对值。 |
· ceil(v instant-vector)：将所有元素的样本值四舍五入v为最接近的整数 | |
· changes(v range-vector)：对于每个输入时间序列，以瞬时向量形式返回其值在指定时间范围内发生变化的次数 | |
· delta(v range-vector)：计算范围向量中每个时间序列元素的第一个值和最后一个值之间的差值v，返回具有给定增量和等效标签的瞬时向量。增量被推断为覆盖范围向量选择器中指定的整个时间范围，因此即使样本值都是整数，也有可能得到非整数结果。 | |
| · 导数。范围向量必须至少有两个样本才能执行计算。当在范围向量中找到+Inf或 时-Inf，计算出的斜率和偏移值将为NaN | |
· deriv(v range-vector)：v使用简单线性回归计算范围向量中时间序列的每秒导数。范围向量必须至少有两个样本才能执行计算。当在范围向量中找到+Inf或 时-Inf，计算出的斜率和偏移值将为NaN | |
· exp(v instant-vector)：计算 中所有元素的指数函数v | |
· floor(v instant-vector)：将所有元素的样本值向下舍入v为最接近的整数。 | |
· holt_winters：(v range-vector, sf scalar, tf scalar)根据 的范围生成时间序列的平滑值v。平滑因子 越低sf，旧数据越重要。趋势因子 越高tf，数据中的趋势考虑得越多。sf和都tf必须介于 0 和 1 之间。 | |
· idelta(v range-vector)：计算范围向量中最后两个样本之间的差异v，返回具有给定增量和等效标签的瞬时向量。 | |
· increase(v range-vector)：计算范围向量中时间序列的增量。 | |
· irate(v range-vector)：计算范围向量中时间序列的每秒瞬时增长率 | |
· ln(v instant-vector)：计算 中所有元素的自然对数v | |
· log2(v instant-vector)：计算 中所有元素的二进制对数v | |
· log10(v instant-vector)：计算 中所有元素的十进制对数v | |
· predict_linear(v range-vector, t scalar)：t根据范围向量v，使用简单线性回归预测从现在开始的时间序列秒的值 。 | |
· rate(v range-vector)：计算范围向量中时间序列的每秒平均增长率。 | |
· resets(v range-vector)：对于每个输入时间序列，以瞬时向量的形式返回在指定时间范围内计数器重置的次数。 | |
· round(v instant-vector, to_nearest=1 scalar)：将所有元素的样本值四舍五入v为最接近的整数。如果出现平局，则向上舍入。 | |
· scalar(v instant-vector)：给定一个单元素输入向量，返回该单元素的样本值作为标量。如果输入向量不只有一个元素，scalar则返回NaN | |
· sgn(v instant-vector)：返回一个向量，其中所有样本值都转换为其符号，定义如下：如果 v 为正，则为 1；如果 v 为负，则为 -1；如果 v 等于零，则为 0。 | |
· sort(v instant-vector)：返回按样本值升序排序的向量元素。原生直方图按其观测值总和排序。 | |
| · `sort_desc()：与 相同sort，但按降序排序。 | |
· sqrt(v instant-vector)：计算 中所有元素的平方根v。 | |
| 特殊说明 | 1.不支持sql单独为{job="localhosts"} ：查询所有指标job为localhosts的数据。PromQL查询必须得指定指标。2.@只能放到selector后面 |
问题说明
1.range查询使用@符号问题
说明：当使用@，会修改整体评估时间(endTime)。而Prometheus是每个粒度上基于该@时间执行PromQL。
2.range查询使用offset问题
说明：当使用offset，会修改整体评估时间(endTime)偏移，同时会导致实际结果值里面的时间也偏移。而Prometheus是每个粒度上基于时间偏移执行PromQL。
3.range查询 range vector 不支持时间区间参数大于时间粒度
说明：当在range查询中有range vector相关PromQL时，range vector中的[1m]范围要小于等于step。如果大于的话，则赋值为为step。
4.subquery中 instant_query参数中不支持包括@ offset
说明：使用subquery时，不支持在里面写 offset和@语句，会导致影响整体评估时间，导致查询时间范围不对。
5.topk和buttomk函数
排序函数在使用分组时结果不准确，目前实现上是基于分组后的所有结果排序，而不是组内排序。