Prometheus提供了一种称为PromQL（Prometheus查询语言）的功能查询语言，使用户可以实时选择和汇总时间序列数据。表达式的结果可以显示为图形，可以在Prometheus的表达式浏览器中显示为表格数据，也可以由外部系统通过HTTP API使用。

示例

本文档仅供参考。为了学习，从几个示例开始可能会更容易。

表达式语言的数据类型

在Prometheus的表达语言中，一个表达式或子表达式可以计算为以下四种类型之一：

  • 即时向量-一组时间序列，每个时间序列包含一个样本，所有样本共享相同的时间戳
  • 范围向量-一组时间序列，其中包含每个时间序列随时间变化的一系列数据点
  • 标量-一个简单的数字浮点值
  • String-一个简单的字符串值；目前未使用

根据使用的查询方法（例如，在绘制图形或显示表达式的输出时），只有其中一些类型是合法的，因为它们是用户指定表达式的结果。例如，返回即时向量的表达式是唯一可以直接绘制图形的类型。

常量 Literals

字符串常量

字符串可以是单引号、双引号或反引号中的文字。
PromQL遵循与Go相同的转义规则。在单引号或双引号反斜杠开头的转义序列，其可以随后a，b，f，n，r，t，v或\。可使用八进制（来提供特定的字符\nnn）或十六进制（\xnn，\unnnn和\Unnnnnnnn）。
反引号内不会处理任何转义。与Go不同，Prometheus不会在反引号内丢弃换行符。
例子：

  1. "this is a string"
  2. 'these are unescaped: \n \\ \t'
  3. `these are not unescaped: \n ' " \t`

浮点常量

标量浮点值可以按以下格式写为文字整数或浮点数（仅包括空格以提高可读性）：

  1. [-+]?(
  2.       [0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?
  3.     | 0[xX][0-9a-fA-F]+
  4.     | [nN][aA][nN]
  5.     | [iI][nN][fF]
  6. )
  1. 例子：
  1. 23
  2. -2.43
  3. 3.4e-9
  4. 0x8f
  5. -Inf
  6. NaN

时间向量选择器

即时向量选择器

即时向量选择器，它允许在给定时间戳(即时)上选择一组时间序列和每个样本的单个样本值。最简单的选择形式，仅指定metric name。这将显示包含所有改metric name的时间序列。
示例：查询metric name为http_requests_total的时间序列：

  1. http_requests_total

通过在花括号（{}）中添加用逗号隔开的标签，可以进一步过滤这些时间序列。
示例：查询metric name为http_requests_total，且具有标签job=prometheus，group=canary的时间序列

  1. http_requests_total{job="prometheus",group="canary"}
  1. 也可以否定地匹配标签值，或将标签值与正则表达式匹配。存在以下标签匹配运算符：
  • =：选择与查询语句字符串相同的标签
  • !=：选择与查询语句字符串不同的标签
  • =~：选择与查询语句字符串可以正则匹配到的标签
  • !=：选择与查询语句字符串不可以正则匹配到的标签

示例：查询metric name为http_requests_total,标签environment的值为：staging 或 testing 或 development且 标签method不为GET的时间序列。

  1. http_requests_total{environment=~"staging|testing|development",method!="GET"}

匹配空标签值时，标签匹配器还会把没有这个标签的时间序列匹配出来。正则表达式是全匹配的。同一个标签名称可以被多种匹配器匹配到。
向量选择器必须指定一个名称或至少与一个不为空的字符串匹配。一下表达式就是非法的：

  1. {job=~".*"} # Bad!
  1. 相反，这些表达式都是有效的，因为他们都具有与空标签值不匹配的选择器。
  1. {job=~".+"}              # Good!
  2. {job=~".*",method="get"} # Good!
  1. 通过与内部标签`__name__`匹配，标签匹配器也可以应用于metric name。例如该表达式`http_requests_total`等效于`{__name__="http_requests_total"}`。同时其它的匹配符号(`!=` `=~` `!~`)也可以用。以下表达式匹配以`job:`开头的matric name：
  1. {__name__=~"job:.*"}
  1. metric name不能是关键字。例如：`bool`, `on`, `ignoring`, `group_left`, `group_right`，以下表达式是非法的：
  1. on{} # Bad!
  1. 解决此问题的方法是使用`__name__`:
  1. {__name__="on"} # Good!
  1. Prometheus中的所有正则表达式都使用[RE2语法](https://github.com/google/re2/wiki/Syntax)。

范围向量选择器

范围矢量工作方式与即时矢量一样。不同的是他从当前即时向量中选择了一定范围的样本。在语法上，在即时向量末尾的[]内加上时间，以指定每个范围向量查询多长时间的样本值。
示例：取时间序列过去5分钟的所有记录值，这些时间序列的matric name为http_requests_total，有一标签job="prometheus"：

  1. http_requests_total{job="prometheus"}[5m]

查询时间

查询时间长度为数字，紧跟其后的是时间单位：

  • ms 毫秒
  • s 秒
  • m 分钟
  • h 小时
  • d 天 24小时
  • w 周 7天
  • y 年 365天

查询时间可以通过串联组合起来。单位必须的是由大到小，且一个单位在一个组合里只能出现一次。
以下是一些有效的时间组合示例：

  1. 5h
  2. 1h30m
  3. 5m
  4. 10s

偏移量修改器

offset可以指定查看个别时刻的数据。
例如，以下表达式返回http_requests_total过去5分钟那个时刻的值：

  1. http_requests_total offset 5m
  1. 请注意，`offset`必须跟随表达式，即以下内容是正确的：
  1. sum(http_requests_total{method="GET"} offset 5m) // GOOD.
  1. 以下是错误的：
  1. sum(http_requests_total{method="GET"}) offset 5m // INVALID.
  1. 范围向量的工作原理相同。<br />示例：返回`http_requests_total`一周前五分钟的速率：
  1. rate(http_requests_total[5m] offset 1w)

为了与时间上的时间偏移量做对比，可以指定负的偏移量：

  1. rate(http_requests_total[5m] offset -1w)
  1. 默认是不可以指定负的偏移量，该功能是被禁用的。需要利用`--enable-feature=promql-negative-offset`启用负偏移量。有关它的详细信息，请参见[禁用功能](https://www.yuque.com/qinjunhang/cn-prometheus/kmguns)。

@修饰符

@允许指定时间的值或指定时间的范围值。提供给@修饰符的时间是unix时间戳，并用float格式。
示例：以下表达式返回该http_requests_toatl指标在2021-01-04T07:40:00+00:00这个时刻的值：

  1. http_requests_total @ 1609746000

与offset类似，但是它查询永远是一个固定时刻的值，但offset只能是根据当前时刻去改变。

请注意，@修饰符必须跟随表达式，即以下内容是正确的：

  1. sum(http_requests_total{method="GET"} @ 1609746000) // GOOD.
  1. 以下示例是不正确的：
  1. sum(http_requests_total{method="GET"}) @ 1609746000 // INVALID.
  1. 范围向量的工作原理相同。这将返回`http_requests_total`在`2021-01-04T07:40:00+00:00`这一时间的五分钟速率：
  1. rate(http_requests_total[5m] @ 1609746000)
  1. `@`修饰符支持在`int64`范围内的所有`float`。他也可以与`offset`一起使用，此时，是相对与`@`指定的时间使用的偏移量，而不论它两的位置前后。示例：如下查询结果相同：
  1. # offset after @
  2. http_requests_total @ 1609746000 offset 5m
  3. # offset before @
  4. http_requests_total offset 5m @ 1609746000
  1. 默认情况下，`@`修饰符是禁用的，因为它打破了PromQL不会提前评估样品的不变性。可以通过设置`--enable-feature=promql-at-modifier`来启用它。有关它的详细信息，请参见[禁用功能](https://www.yuque.com/qinjunhang/cn-prometheus/kmguns)。<br />另外，`start()`和`end()`也可以作为`@`的特殊值。<br />对于范围查询，它们分别解析为范围查询的开始和结尾，并且对于所有步骤都保持相同。<br />对于即时查询，他解析的是评估规则的时间。
  1. http_requests_total @ start()
  2. rate(http_requests_total[5m] @ end())

子查询

子查询允许您针对给定的范围和分辨率运行即时查询。子查询的结果是范围向量。
语法：<instant_query> '[' <range> ':' [<resolution>] ']' [ @ <float_literal> ] [ offset <duration> ]

  • <resolution>是可选的。默认值是全局的评估间隔。

    示例： 先取样过去30分钟的数据，并以1分钟的步长(分辨率)；然后对数据进行5分钟速率的计算。 rate(https_requests_total[5m]) [30m:1m]

运算

Prometheus支持许多二进制和聚合运算。具体可以去表达式运算符页面进行查看。

功能

Prometheus支持多种对数据进行操作的功能。具体可以去表达语言功能页面进行查看。

注释

PromQL支持以开头的行注释#。例子：

  1.    # This is a comment