查询函数

有些函数有默认参数，例如 year(v=vector(time()) instant-vector)。这意味着有一个参数 v，它是一个即时向量，如果未提供，它将默认为表达式 vector(time()) 的值。

`abs()`

abs(v instant-vector) 返回一个向量，其中包含输入向量中所有浮点数样本转换为其绝对值的结果。输入向量中的直方图样本会被静默忽略。

`absent()`

如果传递给它的向量有任何元素（浮点数样本或直方图样本），absent(v instant-vector) 返回一个空向量；如果传递给它的向量没有元素，则返回一个包含单个元素且值为 1 的向量。

这对于在给定指标名称和标签组合不存在时间序列时进行告警非常有用。

absent(nonexistent{job="myjob"})
# => {job="myjob"}

absent(nonexistent{job="myjob",instance=~".*"})
# => {job="myjob"}

absent(sum(nonexistent{job="myjob"}))
# => {}

在前两个示例中，absent() 尝试从输入向量中智能地推导输出的单元素向量的标签。

`absent_over_time()`

如果传递给它的范围向量有任何元素（浮点数样本或直方图样本），absent_over_time(v range-vector) 返回一个空向量；如果传递给它的范围向量没有元素，则返回一个包含单个元素且值为 1 的向量。

这对于在给定指标名称和标签组合在一段时间内不存在时间序列时进行告警非常有用。

absent_over_time(nonexistent{job="myjob"}[1h])
# => {job="myjob"}

absent_over_time(nonexistent{job="myjob",instance=~".*"}[1h])
# => {job="myjob"}

absent_over_time(sum(nonexistent{job="myjob"})[1h:])
# => {}

在前两个示例中，absent_over_time() 尝试从输入向量中智能地推导输出的单元素向量的标签。

`ceil()`

ceil(v instant-vector) 返回一个向量，其中包含输入向量中所有浮点数样本向上取整到大于或等于其原始值的最接近整数值。输入向量中的直方图样本会被静默忽略。

ceil(+Inf) = +Inf
ceil(±0) = ±0
ceil(1.49) = 2.0
ceil(1.78) = 2.0

`changes()`

对于每个输入的时间序列，changes(v range-vector) 返回其值在提供的时间范围内变化的次数，并作为一个即时向量返回。一个浮点数样本后跟一个直方图样本，或者反之，都算作一次变化。一个计数器直方图样本后跟一个具有完全相同值的仪表盘直方图样本，或者反之，不算作变化。

`clamp()`

clamp(v instant-vector, min scalar, max scalar) 将 v 中所有浮点数样本的值限制在下限为 min 和上限为 max 的范围内。输入向量中的直方图样本会被静默忽略。

特殊情况

如果 min > max，则返回一个空向量
如果 min 或 max 是 NaN，浮点数样本将被限制为 NaN

`clamp_max()`

clamp_max(v instant-vector, max scalar) 将 v 中所有浮点数样本的值限制在上限为 max 的范围内。输入向量中的直方图样本会被静默忽略。

`clamp_min()`

clamp_min(v instant-vector, min scalar) 将 v 中所有浮点数样本的值限制在下限为 min 的范围内。输入向量中的直方图样本会被静默忽略。

`day_of_month()`

day_of_month(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并返回每个时间戳的月份中的日期（UTC）。返回值为 1 到 31。输入向量中的直方图样本会被静默忽略。

`day_of_week()`

day_of_week(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并返回每个时间戳的星期几（UTC）。返回值为 0 到 6，其中 0 表示星期日等。输入向量中的直方图样本会被静默忽略。

`day_of_year()`

day_of_year(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并返回每个时间戳的年份中的第几天（UTC）。非闰年的返回值为 1 到 365，闰年为 1 到 366。输入向量中的直方图样本会被静默忽略。

`days_in_month()`

days_in_month(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并返回每个时间戳所在月份的天数（UTC）。返回值为 28 到 31。输入向量中的直方图样本会被静默忽略。

`delta()`

delta(v range-vector) 计算范围向量 v 中每个时间序列元素的第一个值和最后一个值之间的差值，返回一个具有给定增量和等效标签的即时向量。增量被外推以覆盖范围向量选择器中指定的整个时间范围，因此即使样本值都是整数，也可能得到非整数结果。

以下示例表达式返回当前和 2 小时前的 CPU 温度差

delta(cpu_temp_celsius{host="zeus"}[2h])

delta 通过计算一个新的直方图来处理直方图样本，其中每个组件（观测值的总和和计数、桶）都是 v 中第一个和最后一个原生直方图中相应组件之间的差值。但是，v 中在范围内混合了浮点数样本和直方图样本的每个元素将从结果向量中省略，并标记为警告级别的注释。

delta 应该只用于仪表盘（gauge）（对于浮点数和直方图）。

`deriv()`

deriv(v range-vector) 使用简单线性回归计算范围向量 v 中每个浮点数时间序列的每秒导数。范围向量必须至少有两个浮点数样本才能进行计算。当在范围向量中找到 +Inf 或 -Inf 时，计算出的斜率和偏移值将是 NaN。

deriv 应该只用于仪表盘（gauge）且仅对浮点数样本有效。范围向量中仅包含直方图样本的元素将被完全忽略。对于混合了浮点数和直方图样本的元素，只有浮点数样本被用作输入，并标记为信息级别的注释。

`double_exponential_smoothing()`

必须通过特性开关 --enable-feature=promql-experimental-functions 启用此功能。

double_exponential_smoothing(v range-vector, sf scalar, tf scalar) 为 v 范围内每个浮点数时间序列生成一个平滑值。平滑因子 sf 越低，旧数据的重要性越高。趋势因子 tf 越高，数据中的趋势被考虑得越多。sf 和 tf 都必须在 0 和 1 之间。有关更多详细信息，请参阅 NIST 工程统计手册。在 Prometheus V2 中，此函数称为 holt_winters。这造成了混淆，因为 Holt-Winters 方法通常指的是三重指数平滑。这里实现的双重指数平滑也称为“Holt Linear”。

double_exponential_smoothing 应该只用于仪表盘（gauge）且仅对浮点数样本有效。范围向量中仅包含直方图样本的元素将被完全忽略。对于混合了浮点数和直方图样本的元素，只有浮点数样本被用作输入，并标记为信息级别的注释。

`exp()`

exp(v instant-vector) 计算 v 中所有浮点数样本的指数函数。直方图样本会被静默忽略。特殊情况如下

Exp(+Inf) = +Inf
Exp(NaN) = NaN

`floor()`

floor(v instant-vector) 返回一个向量，其中包含输入向量中所有浮点数样本向下取整到小于或等于其原始值的最接近整数值。输入向量中的直方图样本会被静默忽略。

floor(+Inf) = +Inf
floor(±0) = ±0
floor(1.49) = 1.0
floor(1.78) = 1.0

`histogram_avg()`

histogram_avg(v instant-vector) 返回 v 中每个直方图样本中存储的观测值的算术平均值。浮点数样本会被忽略，并且不会出现在返回的向量中。

如下所示使用 histogram_avg 从原生直方图中计算 5 分钟窗口内的平均请求持续时间

histogram_avg(rate(http_request_duration_seconds[5m]))

这等效于以下查询

  histogram_sum(rate(http_request_duration_seconds[5m]))
/
  histogram_count(rate(http_request_duration_seconds[5m]))

`histogram_count()` 和 `histogram_sum()`

histogram_count(v instant-vector) 返回 v 中每个直方图样本中存储的观测值计数。浮点数样本会被忽略，并且不会出现在返回的向量中。

同样，histogram_sum(v instant-vector) 返回每个直方图样本中存储的观测值总和。

通过以下方式使用 histogram_count 从一系列直方图样本中计算观测速率（在此情况下对应于“每秒请求数”）

histogram_count(rate(http_request_duration_seconds[10m]))

`histogram_fraction()`

histogram_fraction(lower scalar, upper scalar, b instant-vector) 返回 b 中包含的每个传统或原生直方图在提供的下限和上限值之间的观测值估计分数。b 中的浮点数样本被视为一个或多个传统直方图的每个桶中的观测值计数，而 b 中的原生直方图样本则每个都被单独视为一个独立的直方图。这与 histogram_quantile() 的工作方式相同。（更多详情请见那里。）

如果提供的下限和上限值与桶边界不重合，计算出的分数是一个估计值，使用与 histogram_quantile() 相同的插值方法。（更多详情请见那里。）尤其对于传统直方图，很容易意外地选择离任何桶边界都很远的下限或上限值，导致较大的误差范围。与其对传统直方图使用 histogram_fraction()，通常更稳健的方法是在计算分数时直接对桶系列进行操作。参见计算 Apdex 分数作为一个典型示例。

例如，以下表达式计算过去一小时内耗时 200 毫秒或更少的 HTTP 请求的分数

histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))

估计的误差取决于底层原生直方图的分辨率以及提供的边界与直方图中桶边界的对齐程度。

+Inf 和 -Inf 是有效的边界值。例如，如果上面表达式中的直方图包含负观测值（这不应该出现在请求持续时间中），则包含所有小于或等于 0.2 的观测值的适当下限将是 -Inf 而不是 0。

提供的边界是包含性还是排他性仅在提供的边界与底层原生直方图中的桶边界精确对齐时才相关。在这种情况下，行为取决于直方图的模式定义。（通常的标准指数模式对于正值都具有包含性上边界和排他性下边界，对于负值则反之。）如果没有精确的边界对齐，函数使用插值来估计分数。由于由此产生的不确定性，边界是包含性还是排他性变得无关紧要。

原生直方图使用标准指数桶的特殊情况：在这种情况下，NaN 观测值被认为在任何桶之外。histogram_fraction(-Inf, +Inf, b) 实际上返回非 NaN 观测值的分数，因此可能小于 1。

`histogram_quantile()`

histogram_quantile(φ scalar, b instant-vector) 从传统直方图或原生直方图中计算 φ-分位数（0 ≤ φ ≤ 1）。（关于 φ-分位数和（传统）直方图指标类型的详细解释，请参阅直方图和摘要。）

b 中的浮点数样本被视为一个或多个传统直方图中每个桶的观测值计数。每个浮点数样本必须有一个标签 le，其中标签值表示桶的包含性上界。（没有此类标签的浮点数样本会被静默忽略。）其他标签和指标名称用于识别属于每个传统直方图的桶。直方图指标类型自动提供带有 _bucket 后缀和适当标签的时间序列。

b 中的（原生）直方图样本每个都被单独视为一个独立的直方图来计算分位数。

只要不出现命名冲突，b 可以包含传统直方图和原生直方图的混合。

使用 rate() 函数指定分位数计算的时间窗口。

示例：一个直方图指标名为 http_request_duration_seconds（因此传统直方图的桶的指标名称是 http_request_duration_seconds_bucket）。要计算过去 10 分钟内请求持续时间的第 90 百分位数，如果 http_request_duration_seconds 是传统直方图，请使用以下表达式

histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))

对于原生直方图，请改用以下表达式

histogram_quantile(0.9, rate(http_request_duration_seconds[10m]))

分位数是为 http_request_duration_seconds 中的每个标签组合计算的。要进行聚合，请在 rate() 函数周围使用 sum() 聚合器。由于 histogram_quantile() 需要 le 标签来处理传统直方图，因此必须将其包含在 by 子句中。以下表达式按 job 聚合传统直方图的第 90 百分位数

histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))

聚合原生直方图时，表达式简化为

histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m])))

要聚合所有传统直方图，请仅指定 le 标签

histogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m])))

对于原生直方图，聚合所有内容按常规方式进行，无需任何 by 子句

histogram_quantile(0.9, sum(rate(http_request_duration_seconds[10m])))

在分位数的值与桶边界不重合的（常见）情况下，histogram_quantile() 函数会在分位数所在桶内插值分位数的值。对于传统直方图、具有自定义桶边界的原生直方图以及其他原生直方图的零桶，它假设桶内的观测值是均匀分布的（也称为*线性插值*）。对于具有标准指数分桶模式的原生直方图的非零桶，插值是在假设桶内的样本以一种方式分布，即它们会均匀地填充一个具有更高分辨率的假设直方图中的桶。（这也称为*指数插值*。更多详情请参见原生直方图规范。）

如果 b 有 0 个观测值，则返回 NaN。对于 φ < 0，返回 -Inf。对于 φ > 1，返回 +Inf。对于 φ = NaN，返回 NaN。

传统直方图的特殊情况

如果 b 包含少于两个桶，则返回 NaN。
最高桶的上界必须是 +Inf。（否则，返回 NaN。）
如果分位数位于最高桶中，则返回第二高桶的上界。
如果最低桶的上界大于 0，则假定该桶的下限为 0。在这种情况下，在该桶内应用通常的线性插值。否则，对于位于最低桶中的分位数，返回最低桶的上界。

原生直方图的特殊情况

如果一个具有标准指数桶的原生直方图有 NaN 观测值，并且分位数落在现有的指数桶之一中，则由于 NaN 观测值被视为 +Inf，结果会偏向更高的值。这会用信息级别的注释进行标记。
如果一个具有标准指数桶的原生直方图有 NaN 观测值，并且分位数落在所有现有指数桶之上，则返回 NaN。这会用信息级别的注释进行标记。
如果直方图在正桶中有观测值，但在负桶中没有，则假定宽度有限的零桶不包含负观测值。
如果直方图在负桶中有观测值，但在正桶中没有，则假定宽度有限的零桶不包含正观测值。

您可以使用 histogram_quantile(0, v instant-vector) 来获取存储在直方图中的估计最小值。

您可以使用 histogram_quantile(1, v instant-vector) 来获取存储在直方图中的估计最大值。

传统直方图的桶是累积的。因此，以下情况应始终成立

桶中的计数是单调递增的（严格非递减）。
两个连续桶的上界之间缺乏观测值会导致这两个桶的计数相等。

然而，浮点精度问题（例如，通过 sum(rate(...)) 计算桶时引入的小差异）或无效数据可能会违反这些假设。在这种情况下，histogram_quantile 将无法返回有意义的结果。为了缓解这个问题，histogram_quantile 假设连续桶之间的微小相对差异是由于浮点精度错误而发生的，并忽略它们。（忽略两个桶之间差异的阈值是两个桶总和的万亿分之一 (1e-12)。）此外，如果即使在此调整后仍存在非单调的桶计数，它们会被增加到前一个桶的值以强制单调性。后者是输入数据存在实际问题的证据，因此会用信息级别的注释标记为 input to histogram_quantile needed to be fixed for monotonicity。如果您遇到此注释，应找到并删除无效数据的来源。

`histogram_stddev()` 和 `histogram_stdvar()`

histogram_stddev(v instant-vector) 返回 v 中每个直方图样本观测值的估计标准差。对于此估计，一个桶中的所有观测值都被假定为桶边界的平均值。对于零桶和具有自定义边界的桶，使用算术平均值。对于通常的指数桶，使用几何平均值。浮点数样本会被忽略，并且不会出现在返回的向量中。

同样，histogram_stdvar(v instant-vector) 返回 v 中每个直方图样本观测值的估计标准方差。

`hour()`

hour(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并返回每个时间戳的小时（UTC）。返回值为 0 到 23。输入向量中的直方图样本会被静默忽略。

`idelta()`

idelta(v range-vector) 计算范围向量 v 中最后两个样本之间的差值，返回一个具有给定增量和等效标签的即时向量。两个样本都必须是浮点数样本或直方图样本。v 中最后两个样本一个是浮点数样本而另一个是直方图样本的元素将从结果向量中省略，并标记为警告级别的注释。

idelta 应该只用于仪表盘（gauge）（对于浮点数和直方图）。

`increase()`

increase(v range-vector) 计算范围向量中时间序列的增量。单调性的中断（例如由于目标重启导致的计数器重置）会自动调整。增量被外推以覆盖范围向量选择器中指定的整个时间范围，因此即使计数器仅以整数增量增加，也可能得到非整数结果。

以下示例表达式返回过去 5 分钟内测量的 HTTP 请求数，按范围向量中的时间序列

increase(http_requests_total{job="api-server"}[5m])

increase 通过计算一个新的直方图来处理直方图样本，其中每个组件（观测值的总和和计数、桶）都是 v 中第一个和最后一个原生直方图中相应组件之间的增量。但是，v 中在范围内混合了浮点数样本和直方图样本的每个元素将从结果向量中省略，并标记为警告级别的注释。

increase 应该只用于计数器（counter）（对于浮点数和直方图）。它是 rate(v) 乘以指定时间范围窗口下的秒数的语法糖，主要应用于提高可读性。在记录规则中使用 rate，以便以每秒为基础持续跟踪增量。

`info()`

info 函数是一个实验，旨在改善包含来自信息指标标签的用户体验。此函数的行为可能会在 Prometheus 的未来版本中发生变化，包括从 PromQL 中移除。必须通过特性开关 --enable-feature=promql-experimental-functions 启用 info。

info(v instant-vector, [data-label-selector instant-vector]) 函数为 v 中的每个时间序列查找所有具有匹配*识别*标签（稍后详述）的 info 序列，并将其*数据*（即非识别）标签的并集添加到该时间序列中。第二个参数 data-label-selector 是可选的。它不是一个真正的即时向量，但使用了其语法的一个子集。它必须以花括号（{ ... }）开始和结束，并且只能包含标签匹配器。标签匹配器用于限制要考虑的 info 序列以及要添加到 v 的数据标签。

info 序列的识别标签是唯一标识该 info 序列的标签子集。其余的标签被认为是*数据标签*（也称为非识别标签）。（请注意，Prometheus 的时间序列身份概念总是包含*所有*标签。为了 info 函数的目的，我们“逻辑上”定义 info 序列身份的方式与传统的 Prometheus 视图不同。）info 序列的识别标签用于将其连接到常规（非 info）序列，即那些与 info 序列的识别标签具有相同标签的序列。数据标签，即通过 info 函数添加到常规序列的标签，有效地编码了元数据键值对。（这意味着，在传统的 Prometheus 视图中，数据标签的更改构成了一个 info 序列的结束和另一个新 info 序列的开始，而 info 函数的“逻辑”视图是同一个 info 序列继续存在，只是“数据”不同。）

添加数据标签的传统方法有时被称为“连接查询”，如下例所示：

  rate(http_server_request_duration_seconds_count[2m])
* on (job, instance) group_left (k8s_cluster_name)
  target_info

该查询的核心是表达式 rate(http_server_request_duration_seconds_count[2m])。但要从 info 指标中添加数据标签，用户必须使用复杂（且不直观）的语法来指定要使用的 info 指标（target_info）、识别标签是什么（on (job, instance)），以及要添加哪些数据标签（group_left (k8s_cluster_name)）。

这个查询不仅冗长难写，还可能遇到“身份危机”：如果 target_info 的任何数据标签发生变化，Prometheus 会将其视为序列的变化（如上所述，Prometheus 原生没有非识别标签的概念）。如果旧的 target_info 序列没有被正确标记为过时（在某些摄取路径下可能会发生这种情况），则上述查询将失败长达 5 分钟（回溯增量），因为它会发现与新旧版本的 target_info 存在冲突匹配。

info 函数不仅解决了这种冲突，倾向于使用较新的序列，而且还简化了语法，因为它了解可用的 info 序列及其识别标签是什么。使用 info 函数的示例查询如下所示：

info(
  rate(http_server_request_duration_seconds_count[2m]),
  {k8s_cluster_name=~".+"}
)

通过完全省略 info 函数的第二个参数，可以实现添加*所有*数据标签的常见情况，从而进一步简化示例：

info(rate(http_server_request_duration_seconds_count[2m]))

虽然 info 通常会自动查找所有匹配的 info 序列，但也可以通过提供一个 __name__ 标签匹配器来限制它们，例如 {__name__="target_info"}。

局限性

在当前迭代中，info 默认只考虑名为 target_info 的 info 序列。它还假设识别 info 序列的标签是 instance 和 job。然而，info 确实通过 __name__ 标签匹配器支持其他 info 序列名称。例如，可以明确指定同时考虑 target_info 和 build_info，如下所示：{__name__=~"(target|build)_info"}。但是，识别标签必须始终是 instance 和 job。

这些局限性部分地违背了 info 函数的初衷。在现阶段，这是一个实验，旨在了解该方法在实践中的用处。info 函数的最终版本确实会考虑所有匹配的 info 序列及其适当的识别标签。

`irate()`

irate(v range-vector) 计算范围向量中时间序列的瞬时每秒增长率。这基于最后两个数据点。单调性的中断（例如由于目标重启导致的计数器重置）会自动调整。两个样本必须都是浮点样本或直方图样本。v 中最后两个样本一个是浮点样本另一个是直方图样本的元素将从结果向量中省略，并通过警告级别的注释进行标记。

irate 只应与计数器一起使用（对于浮点数和直方图）。

以下示例表达式返回每个时间序列在范围向量中最近两个数据点上，回顾最多 5 分钟的 HTTP 请求的每秒速率：

irate(http_requests_total{job="api-server"}[5m])

irate 只应在绘制易变、快速变化的计数器图表时使用。对于警报和慢速变化的计数器，请使用 rate，因为速率的短暂变化可能会重置 FOR 子句，而且完全由罕见尖峰组成的图表难以阅读。

请注意，当将 irate() 与聚合运算符（例如 sum()）或随时间聚合的函数（任何以 _over_time 结尾的函数）结合使用时，应始终先执行 irate()，然后再进行聚合。否则，当目标重启时，irate() 无法检测到计数器重置。

`label_join()`

对于 v 中的每个时间序列，label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...) 使用 separator 连接所有 src_labels 的值，并返回带有包含连接后值的 dst_label 标签的时间序列。此函数中可以有任意数量的 src_labels。

label_join 对浮点和直方图样本的作用方式相同。

此示例将返回一个向量，其中每个时间序列都添加了一个值为 a,b,c 的 foo 标签：

label_join(up{job="api-server",src1="a",src2="b",src3="c"}, "foo", ",", "src1", "src2", "src3")

`label_replace()`

对于 v 中的每个时间序列，label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string) 会将正则表达式 regex 与标签 src_label 的值进行匹配。如果匹配，返回的时间序列中 dst_label 标签的值将是 replacement 的展开，并包含输入中的原始标签。正则表达式中的捕获组可以用 $1、$2 等引用。正则表达式中的命名捕获组可以用 $name 引用（其中 name 是捕获组名称）。如果正则表达式不匹配，则返回的时间序列保持不变。

label_replace 对浮点和直方图样本的作用方式相同。

此示例将返回在 service 标签处值为 a:c、在 foo 标签处值为 a 的时间序列：

label_replace(up{job="api-server",service="a:c"}, "foo", "$1", "service", "(.*):.*")

第二个示例与第一个示例效果相同，并演示了命名捕获组的使用：

label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P<name>.*):(?P<version>.*)")

`ln()`

ln(v instant-vector) 计算 v 中所有浮点样本的自然对数。输入向量中的直方图样本会被静默忽略。特殊情况如下：

ln(+Inf) = +Inf
ln(0) = -Inf
ln(x < 0) = NaN
ln(NaN) = NaN

`log2()`

log2(v instant-vector) 计算 v 中所有浮点样本的二进制对数。输入向量中的直方图样本会被静默忽略。特殊情况与 ln 中的相同。

`log10()`

log10(v instant-vector) 计算 v 中所有浮点样本的十进制对数。输入向量中的直方图样本会被静默忽略。特殊情况与 ln 中的相同。

`minute()`

minute(v=vector(time()) instant-vector) 将 v 中的浮点样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并为每个时间戳返回小时中的分钟（UTC 时间）。返回值为 0 到 59。输入向量中的直方图样本会被静默忽略。

`month()`

month(v=vector(time()) instant-vector) 将 v 中的浮点样本解释为时间戳（自 1970 年 1 月 1 日 UTC 以来的秒数），并为每个时间戳返回年份中的月份（UTC 时间）。返回值为 1 到 12，其中 1 表示一月，依此类推。输入向量中的直方图样本会被静默忽略。

`predict_linear()`

predict_linear(v range-vector, t scalar) 基于范围向量 v，使用简单线性回归预测 t 秒后时间序列的值。范围向量必须至少有两个浮点样本才能进行计算。当在范围向量中发现 +Inf 或 -Inf 时，预测值将为 NaN。

predict_linear 只应与仪表盘（gauges）一起使用，并且只对浮点样本有效。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点和直方图样本混合的元素，仅使用浮点样本作为输入，并通过信息级别的注释进行标记。

`rate()`

rate(v range-vector) 计算范围向量中时间序列的每秒平均增长率。单调性的中断（例如由于目标重启导致的计数器重置）会自动调整。此外，计算会外推到时间范围的末端，允许遗漏抓取或抓取周期与范围时间段的不完美对齐。

以下示例表达式返回每个时间序列在范围向量中过去 5 分钟内 HTTP 请求的每秒平均速率：

rate(http_requests_total{job="api-server"}[5m])

rate 作用于原生直方图，通过计算一个新的直方图，其中每个组件（观测值的总和和计数、桶）都是 v 中第一个和最后一个原生直方图中相应组件之间的增长率。但是，v 中在范围内包含浮点和原生直方图样本混合的每个元素将从结果向量中省略，并通过警告级别的注释进行标记。

rate 只应与计数器一起使用（对于浮点数和直方图）。它最适合用于警报和慢速变化的计数器图表。

请注意，当将 rate() 与聚合运算符（例如 sum()）或随时间聚合的函数（任何以 _over_time 结尾的函数）结合使用时，应始终先执行 rate()，然后再进行聚合。否则，当目标重启时，rate() 无法检测到计数器重置。

`resets()`

对于每个输入时间序列，resets(v range-vector) 以即时向量的形式返回在提供的时间范围内的计数器重置次数。两个连续浮点样本之间的值下降被解释为计数器重置。原生直方图中的重置检测更为复杂：任何桶（包括零桶）或观测计数的任何减少都构成计数器重置，但也包括任何先前填充的桶消失、零桶宽度减小或任何不兼容的分辨率降低的模式更改。

resets 只应与计数器一起使用（对于浮点数和直方图）。

一个浮点样本后跟一个直方图样本，反之亦然，算作一次重置。一个计数器直方图样本后跟一个仪表盘直方图样本，反之亦然，也算作一次重置（但请注意，resets 本就不应用于仪表盘，见上文）。

`round()`

round(v instant-vector, to_nearest=1 scalar) 将 v 中所有元素的样本值四舍五入到最接近的整数。平局通过向上取整解决。可选的 to_nearest 参数允许指定样本值应四舍五入到的最接近的倍数。这个倍数也可以是分数。输入向量中的直方图样本会被静默忽略。

`scalar()`

给定一个只包含一个带浮点样本元素的输入向量，scalar(v instant-vector) 将该浮点样本的值作为标量返回。如果输入向量不恰好包含一个带浮点样本的元素，scalar 将返回 NaN。输入向量中的直方图样本会被静默忽略。

`sgn()`

sgn(v instant-vector) 返回一个向量，其中所有浮点样本值都转换为其符号，定义如下：如果 v 为正数，则为 1；如果 v 为负数，则为 -1；如果 v 等于零，则为 0。输入向量中的直方图样本会被静默忽略。

`sort()`

sort(v instant-vector) 返回按浮点样本值升序排序的向量元素。输入向量中的直方图样本会被静默忽略。

请注意，sort 只影响即时查询的结果，因为范围查询结果总是有固定的输出顺序。

`sort_desc()`

与 sort 相同，但按降序排序。

`sort_by_label()`

必须通过特性开关 --enable-feature=promql-experimental-functions 启用此功能。

sort_by_label(v instant-vector, label string, ...) 返回按给定标签值升序排序的向量元素。如果这些标签值相等，则元素按其完整的标签集排序。sort_by_label 对浮点和直方图样本的作用方式相同。

请注意，sort_by_label 只影响即时查询的结果，因为范围查询结果总是有固定的输出顺序。

sort_by_label 使用自然排序顺序。

`sort_by_label_desc()`

必须通过特性开关 --enable-feature=promql-experimental-functions 启用此功能。

与 sort_by_label 相同，但按降序排序。

`sqrt()`

sqrt(v instant-vector) 计算 v 中所有浮点样本的平方根。输入向量中的直方图样本会被静默忽略。

`time()`

time() 返回自 1970 年 1 月 1 日 UTC 以来的秒数。请注意，这实际上不是返回当前时间，而是表达式将被评估的时间。

`timestamp()`

timestamp(v instant-vector) 将给定向量的每个样本的时间戳作为自 1970 年 1 月 1 日 UTC 以来的秒数返回。它对浮点和直方图样本的作用方式相同。

`vector()`

vector(s scalar) 将标量 s 转换为浮点样本，并将其作为无标签的单元素即时向量返回。

`year()`

year(v=vector(time()) instant-vector) 返回给定时间在 UTC 的年份。输入向量中的直方图样本会被静默忽略。

`<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): 指定间隔内最新的样本。
present_over_time(range-vector): 对于指定间隔内的任何序列，值为 1。

如果设置了功能标志 --enable-feature=promql-experimental-functions，则可以使用以下附加函数：

mad_over_time(range-vector): 指定间隔内所有浮点样本的中位数绝对偏差。
ts_of_min_over_time(range-vector): 指定间隔内具有最小值的最后一个浮点样本的时间戳。
ts_of_max_over_time(range-vector): 指定间隔内具有最大值的最后一个浮点样本的时间戳。
ts_of_last_over_time(range-vector): 指定间隔内最后一个样本的时间戳。
first_over_time(range-vector): 指定间隔内最旧的样本。
ts_of_first_over_time(range-vector): 指定间隔内最早样本的时间戳。

请注意，指定间隔内的所有值在聚合中具有相同的权重，即使这些值在整个间隔内分布不均匀。

这些函数对直方图的作用如下：

count_over_time、first_over_time、last_over_time 和 present_over_time() 对浮点和直方图样本的作用方式相同。
avg_over_time() 和 sum_over_time() 对直方图样本的作用方式与相应的聚合运算符相对应。如果一个序列在范围内包含浮点样本和直方图样本的混合，则相应的结果将从输出向量中完全移除。这种移除会通过警告级别的注释进行标记。
所有其他函数都以以下方式忽略直方图样本：仅包含直方图样本的输入范围会从输出中静默移除。对于包含直方图和浮点样本混合的范围，仅处理浮点样本，而忽略直方图样本会通过信息级别的注释进行标记。

first_over_time(m[1m]) 与 m offset 1m 的不同之处在于，前者将选择 1m 范围内 m 的第一个样本，而 m offset 1m 将选择 1m 偏移量*之外且之前*的回溯间隔内最新的样本。这在范围查询中使用 first_over_time(m[step()]) 时特别有用（当设置了 --enable-feature=promql-duration-expr 时可用），以确保所选样本在范围步骤内。

三角函数

三角函数以弧度为单位工作。它们会忽略输入向量中的直方图样本。

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 中所有浮点样本的双曲正切值 (特殊情况 )。

以下函数可用于在角度和弧度之间转换：

deg(v instant-vector): 将 v 中所有浮点样本从弧度转换为角度。
pi(): 返回圆周率 pi。
rad(v instant-vector): 将 v 中所有浮点样本从角度转换为弧度。

本页内容

查询函数

abs()

absent()

absent_over_time()

ceil()

changes()

clamp()

clamp_max()

clamp_min()

day_of_month()

day_of_week()

day_of_year()

days_in_month()

delta()

deriv()

double_exponential_smoothing()

exp()

floor()

histogram_avg()

histogram_count() 和 histogram_sum()

histogram_fraction()

histogram_quantile()

histogram_stddev() 和 histogram_stdvar()

hour()

idelta()

increase()

info()

局限性

irate()

label_join()

label_replace()

ln()

log2()

log10()

minute()

month()

predict_linear()

rate()

resets()

round()

scalar()

sgn()

sort()

sort_desc()

sort_by_label()

sort_by_label_desc()

sqrt()

time()

timestamp()

vector()

year()

<aggregation>_over_time()

三角函数

`abs()`

`absent()`

`absent_over_time()`

`ceil()`

`changes()`

`clamp()`

`clamp_max()`

`clamp_min()`

`day_of_month()`

`day_of_week()`

`day_of_year()`

`days_in_month()`

`delta()`

`deriv()`

`double_exponential_smoothing()`

`exp()`

`floor()`

`histogram_avg()`

`histogram_count()` 和 `histogram_sum()`

`histogram_fraction()`

`histogram_quantile()`

`histogram_stddev()` 和 `histogram_stdvar()`

`hour()`

`idelta()`

`increase()`

`info()`

`irate()`

`label_join()`

`label_replace()`

`ln()`

`log2()`

`log10()`

`minute()`

`month()`

`predict_linear()`

`rate()`

`resets()`

`round()`

`scalar()`

`sgn()`

`sort()`

`sort_desc()`

`sort_by_label()`

`sort_by_label_desc()`

`sqrt()`

`time()`

`timestamp()`

`vector()`

`year()`

`<aggregation>_over_time()`