查询函数

某些函数具有默认参数，例如 year(v=vector(time()) instant-vector)。这意味着该函数有一个参数 v，它是一个瞬时向量 (instant vector)；如果没有提供该参数，它将默认使用表达式 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 中的元素在范围内混合了浮点样本和直方图样本，则该元素将被排除在结果向量之外，并产生一条警告级别的注解。

delta 仅应与仪表（gauge）一起使用（适用于浮点数和直方图）。

`deriv()`

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

deriv 仅应与仪表一起使用，并且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点和直方图样本混合的元素，仅使用浮点样本作为输入，并产生一条信息级别的注解。

`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 线性”。

double_exponential_smoothing 仅应与仪表一起使用，并且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点和直方图样本混合的元素，仅使用浮点样本作为输入，并产生一条信息级别的注解。

`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 分数计算作为典型示例。

例如，以下表达式计算了过去一小时内 HTTP 请求中耗时 200ms 或更短的占比

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）。若 http_request_duration_seconds 是一个经典直方图，要计算过去 10 分钟内请求持续时间的第 90 百分位，请使用以下表达式

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_quantiles()`

此函数必须通过功能标志 --enable-feature=promql-experimental-functions 启用。

histogram_quantiles(v instant-vector, quantile_label string, φ_1 scalar, φ_2 scalar, ...) 从经典直方图或原生直方图中计算多个（1 到 10 个）φ-分位数（0 ≤ φ ≤ 1）。分位数计算的工作方式与 histogram_quantile() 相同。第二个参数（字符串）指定用于在查询结果中标识不同分位数的标签名称。

histogram_quantiles(sum(rate(foo[1m])), "quantile", 0.9, 0.99)
# => {quantile="0.9"} 123
     {quantile="0.99"} 128

`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 应仅用于仪表（对于浮点数和直方图）。

`increase()`

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

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

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

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

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

`info()`

info 函数是一项旨在改善包含来自 info 指标的标签的 UX 的实验。此函数的行为在 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 函数的需要，我们与传统的 Prometheus 视图相比，“逻辑上”以不同的方式定义了 info 序列标识。）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 函数的第 2 个参数来实现，从而使示例更加简单

info(rate(http_server_request_duration_seconds_count[2m]))

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

请注意，如果 v 中有任何时间序列与 data-label-selector（或如果不指定该参数，则为默认的 target_info）匹配，它们将被视为 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 应仅用于计数器（对于浮点数和直方图）。

以下示例表达式返回范围向量中每个时间序列的 HTTP 请求每秒速率（回顾过去 5 分钟，查看最近的两个数据点）

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 应仅用于仪表，并且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点和直方图样本混合的元素，仅使用浮点样本作为输入，这由信息级注释标记。

`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 的区别在于，前者将选择 1 分钟范围内的 m 的第一个样本，而 m offset 1m 将选择回溯区间外且先于 1 分钟偏移的最近样本。这在范围查询中使用 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_quantiles()

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_quantiles()`

`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()`