Prometheus 提供了一种称为 PromQL（Prometheus 查询语言）的功能性查询语言，允许用户实时选择和聚合时间序列数据。
当你向 Prometheus 发送查询请求时，它可以是即时查询（在某个时间点求值），也可以是范围查询（在开始时间和结束时间之间以等间隔的步长求值）。PromQL 在这两种情况下工作方式完全相同；范围查询就像在不同时间戳多次运行即时查询一样。
在 Prometheus UI 中，“Table” 选项卡用于即时查询，“Graph” 选项卡用于范围查询。
其他程序可以通过 HTTP API 获取 PromQL 表达式的结果。
本文档是 Prometheus 基础语言参考。为了学习，从一些示例开始可能会更容易。
在 Prometheus 的表达式语言中，表达式或子表达式可以求值为以下四种类型之一
根据使用场景（例如绘图与显示表达式输出），只有其中一些类型可以用作用户指定表达式的结果。对于即时查询，以上任何数据类型都可以作为表达式的根。 范围查询只支持标量类型和即时向量类型的表达式。
关于实验性原生直方图的说明
字符串字面量可以用单引号、双引号或反引号指定。
PromQL 遵循与 Go 相同的转义规则。对于单引号或双引号中的字符串字面量，反斜杠开始一个转义序列，后面可以是 a、b、f、n、r、t、v 或 \。可以使用八进制 (\nnn) 或十六进制 (\xnn、\unnnn 和 \Unnnnnnnn) 表示法提供特定字符。
相反，在反引号指定的字符串字面量中不解析转义字符。需要注意的是，与 Go 不同，Prometheus 不会丢弃反引号内的换行符。
示例
"this is a string"
'these are unescaped: \n \\ \t'
`these are not unescaped: \n ' " \t`
标量浮点数值可以写成字面整数或浮点数，格式如下（空格仅为提高可读性）：
[-+]?(
[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?
| 0[xX][0-9a-fA-F]+
| [nN][aA][nN]
| [iI][nN][fF]
)
示例
23
-2.43
3.4e-9
0x8f
-Inf
NaN
此外，下划线 (_) 可用于十进制或十六进制数字之间，以提高可读性。
示例
1_000_000
.123_456_789
0x_53_AB_F3_82
浮点数字面量也用于指定以秒为单位的持续时间。为方便起见，十进制整数可以与以下时间单位结合使用
ms – 毫秒s – 秒 – 1秒等于 1000毫秒m – 分钟 – 1分钟等于 60秒（忽略闰秒）h – 小时 – 1小时等于 60分钟d – 天 – 1天等于 24小时（忽略所谓的夏令时）w – 周 – 1周等于 7天y – 年 – 1年等于 365天（忽略闰日）在十进制整数后面加上上述单位之一，是裸浮点数字面量表示等效秒数的另一种方式。
示例
1s # Equivalent to 1.
2m # Equivalent to 120.
1ms # Equivalent to 0.001.
-2h # Equivalent to -7200.
以下示例不起作用
0xABm # No suffixing of hexadecimal numbers.
1.5h # Time units cannot be combined with a floating point.
+Infd # No suffixing of ±Inf or NaN.
多个单位可以通过带后缀整数的串联组合。单位必须按从长到短的顺序排列。每个浮点数字面量中，给定单位只能出现一次。
示例
1h30m # Equivalent to 5400s and thus 5400.
12h34m56s # Equivalent to 45296s and thus 45296.
54s321ms # Equivalent to 54.321.
这些是基本组成部分，用于指示 PromQL 要获取哪些数据。
即时向量选择器允许选择一组时间序列，并在给定时间戳（时间点）为每条时间序列选择一个样本值。最简单的形式是只指定一个指标名称，这将产生一个即时向量，其中包含所有具有该指标名称的时间序列的元素。
返回的值是查询评估时间戳（对于即时查询）或查询当前步长（对于范围查询）时或之前的最新样本的值。@ 修饰符允许覆盖选择发生所参照的时间戳。只有当时间序列的最新样本晚于回溯期时，才会返回该时间序列。
此示例选择所有具有 http_requests_total 指标名称的时间序列，返回每条时间序列的最新样本
http_requests_total
可以通过在花括号 ({}) 中附加逗号分隔的标签匹配器列表来进一步过滤这些时间序列。
此示例仅选择具有 http_requests_total 指标名称，并且 job 标签设置为 prometheus 且 group 标签设置为 canary 的时间序列
http_requests_total{job="prometheus",group="canary"}
也可以否定匹配标签值，或使用正则表达式匹配标签值。存在以下标签匹配操作符
=: 选择与提供的字符串完全相等的标签。!=: 选择与提供的字符串不相等的标签。=~: 选择与提供的字符串正则匹配的标签。!~: 选择与提供的字符串不正则匹配的标签。正则匹配是完全锚定的。env=~"foo" 的匹配被视为 env=~"^foo$"。
例如，这会选择所有用于 staging、testing 和 development 环境以及除 GET 以外的 HTTP 方法的 http_requests_total 时间序列。
http_requests_total{environment=~"staging|testing|development",method!="GET"}
匹配空标签值的标签匹配器也会选择所有根本没有设置特定标签的时间序列。同一个标签名称可以有多个匹配器。
例如，给定数据集
http_requests_total
http_requests_total{replica="rep-a"}
http_requests_total{replica="rep-b"}
http_requests_total{environment="development"}
查询 http_requests_total{environment=""} 将匹配并返回
http_requests_total
http_requests_total{replica="rep-a"}
http_requests_total{replica="rep-b"}
并排除
http_requests_total{environment="development"}
同一个标签名称可以使用多个匹配器；它们必须全部通过才能返回结果。
查询
http_requests_total{replica!="rep-a",replica=~"rep.*"}
则将匹配
http_requests_total{replica="rep-b"}
向量选择器必须指定名称或至少一个不匹配空字符串的标签匹配器。以下表达式是非法的
{job=~".*"} # Bad!
相反，这些表达式是有效的，因为它们都有一个不匹配空标签值的选择器。
{job=~".+"} # Good!
{job=~".*",method="get"} # Good!
标签匹配器也可以通过匹配内部的 __name__ 标签应用于指标名称。例如，表达式 http_requests_total 等同于 {__name__="http_requests_total"}。 除了 = 之外的匹配器 (!=, =~, !~) 也可以使用。以下表达式选择所有名称以 job: 开头的指标
{__name__=~"job:.*"}
指标名称不得是关键字 bool、on、ignoring、group_left 和 group_right 之一。以下表达式是非法的
on{} # Bad!
对此限制的解决方法是使用 __name__ 标签
{__name__="on"} # Good!
范围向量字面量的工作方式与即时向量字面量类似，但它们从当前时刻向后选择一段时间范围内的样本。语法上，在向量选择器末尾的方括号 ([]) 中附加一个浮点数字面量，用于指定要为每个结果范围向量元素获取多久之前的数值。通常，浮点数字面量使用带有一个或多个时间单位的语法，例如 [5m]。该范围是左开右闭区间，即时间戳与范围左边界重合的样本被排除在选择之外，而时间戳与范围右边界重合的样本被包含在选择之内。
此示例中，我们选择所有具有指标名称 http_requests_total 且 job 标签设置为 prometheus 的时间序列在过去 5 分钟内记录的所有值
http_requests_total{job="prometheus"}[5m]
offset 修饰符允许更改查询中单个即时向量和范围向量的时间偏移。
例如，以下表达式返回相对于当前查询评估时间点，5 分钟之前的 http_requests_total 的值
http_requests_total offset 5m
请注意，offset 修饰符必须始终紧随选择器之后，例如以下用法是正确的
sum(http_requests_total{method="GET"} offset 5m) // GOOD.
而以下用法是不正确的
sum(http_requests_total{method="GET"}) offset 5m // INVALID.
范围向量同样适用。这返回 http_requests_total 在一周前的 5 分钟内的速率
rate(http_requests_total[5m] offset 1w)
当查询过去样本时，负偏移将允许进行时间上的向前比较
rate(http_requests_total[5m] offset -1w)
请注意，这允许查询查看其评估时间点之后的数据。
@ 修饰符允许更改查询中单个即时向量和范围向量的评估时间。提供给 @ 修饰符的时间是一个 Unix 时间戳，并用浮点数字面量描述。
例如，以下表达式返回 http_requests_total 在时间点 2021-01-04T07:40:00+00:00 的值
http_requests_total @ 1609746000
请注意，@ 修饰符必须始终紧随选择器之后，例如以下用法是正确的
sum(http_requests_total{method="GET"} @ 1609746000) // GOOD.
而以下用法是不正确的
sum(http_requests_total{method="GET"}) @ 1609746000 // INVALID.
范围向量同样适用。这返回 http_requests_total 在时间点 2021-01-04T07:40:00+00:00 的 5 分钟速率
rate(http_requests_total[5m] @ 1609746000)
@ 修饰符支持上述所有数字字面量表示。它与 offset 修饰符一起使用时，偏移量相对于 @ 修饰符的时间应用。无论修饰符的顺序如何，结果都是相同的。
例如，这两个查询将产生相同的结果
# offset after @
http_requests_total @ 1609746000 offset 5m
# offset before @
http_requests_total offset 5m @ 1609746000
此外，start() 和 end() 也可以作为特殊值用于 @ 修饰符。
对于范围查询，它们分别解析为范围查询的开始和结束时间，并在所有步骤中保持相同。
对于即时查询，start() 和 end() 都解析为评估时间。
http_requests_total @ start()
rate(http_requests_total[5m] @ end())
请注意，@ 修饰符允许查询查看其评估时间点之后的数据。
子查询允许你对给定的范围和分辨率运行即时查询。子查询的结果是范围向量。
语法: <instant_query> '[' <range> ':' [<resolution>] ']' [ @ <float_literal> ] [ offset <float_literal> ]
<resolution> 是可选的。默认为全局评估间隔。Prometheus 支持许多二进制和聚合操作符。这些操作符在表达式语言操作符页面中有详细描述。
Prometheus 支持多种数据操作函数。这些函数在表达式语言函数页面中有详细描述。
PromQL 支持以 # 开头的行注释。示例
# This is a comment
Prometheus 中的所有正则表达式都使用 RE2 语法。
正则匹配始终是完全锚定的。
在查询期间，采样数据的时间戳选择独立于实际当前的时间序列数据。这主要是为了支持聚合（sum、avg 等）等情况，其中多个聚合的时间序列在时间上不精确对齐。由于其独立性，Prometheus 需要在这些时间戳为每个相关时间序列分配一个值。它通过选取早于回溯期的最新样本来实现。回溯期默认为 5 分钟，但可以通过--query.lookback-delta 标志进行设置。
如果抓取目标或规则评估不再为先前存在的时间序列返回样本，则此时间序列将被标记为陈旧。如果目标被移除，则之前检索到的时间序列将在移除后很快被标记为陈旧。
如果查询在时间序列被标记为陈旧后的采样时间戳进行评估，则该时间序列不会返回任何值。如果随后为该时间序列摄取了新的样本，它们将按预期返回。
当时间序列不再导出或目标不再存在时，它将变为陈旧。此类时间序列将在其最后收集的样本时间点从图表中消失，并且在被标记为陈旧后将不会在查询中返回。
一些在样本上放置自己的时间戳的导出器会表现出不同的行为：停止导出的序列会保持最后一个值（默认情况下）5 分钟，然后消失。track_timestamps_staleness 设置可以改变这一点。
如果查询需要处理大量数据，对其进行绘图可能会超时或使服务器或浏览器过载。因此，在对未知数据构建查询时，请始终先在 Prometheus 的表达式浏览器表格视图中构建查询，直到结果集看起来合理（最多几百条，而不是几千条时间序列）。只有充分过滤或聚合数据后，再切换到图表模式。如果表达式仍然需要太长时间进行临时绘图，请通过记录规则预先记录它。
这对于 Prometheus 的查询语言尤其重要，其中像 api_http_requests_total 这样的裸指标名称选择器可能会扩展到带有不同标签的数千条时间序列。此外，请记住，即使输出只有少量时间序列，对许多时间序列进行聚合的表达式也会在服务器上产生负载。这类似于在关系型数据库中对某列的所有值求和会很慢，即使输出值只是一个数字。
本文档是开源的。请通过提交 issue 或 pull request 来帮助改进它。