查询基础知识 | 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 环境以及 HTTP 方法不是 GET 的所有 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 时间戳，并用浮点字面量描述。

例如，以下表达式返回 2021-01-04T07:40:00+00:00 时的 http_requests_total 值

http_requests_total @ 1609746000

请注意，@ 修饰符始终需要紧跟在选择器之后，即以下内容是正确的

sum(http_requests_total{method="GET"} @ 1609746000) // GOOD.

而以下内容是不正确的

sum(http_requests_total{method="GET"}) @ 1609746000 // INVALID.

范围向量也适用相同的方法。这返回 2021-01-04T07:40:00+00:00 时 http_requests_total 的 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 这样的裸指标名称选择器可能会扩展到数千个带有不同标签的时间序列。此外，请记住，即使输出仅是少量时间序列，对许多时间序列进行聚合的表达式也会在服务器上产生负载。这类似于在关系数据库中对列的所有值求和的速度很慢，即使输出值只是一个数字。

本文档是开源的。请通过提交问题或拉取请求来帮助改进它。

查询 Prometheus

示例

表达式语言数据类型

字面量

字符串字面量