查询函数

某些函数具有默认参数，例如 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() 会尝试智能地从输入向量中推导出 1 元素输出向量的标签。

`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() 会尝试智能地从输入向量中推导出 1 元素输出向量的标签。

`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 仅应与仪表类型（浮点和直方图）一起使用。

`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 Linear)。

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

例如，以下表达式计算过去一小时内耗时 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 仅应用于仪表类型（浮点和直方图）。

`increase()`

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

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

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

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

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

`info()`

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

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

信息序列的识别标签是唯一标识该信息序列的标签子集。其余标签被视为数据标签（也称为非识别标签）。（请注意，Prometheus 的时间序列标识概念始终包含所有标签。为了info函数的目的，我们“逻辑上”以不同于传统 Prometheus 视图的方式定义信息序列标识。）信息序列的识别标签用于将其与常规（非信息）序列连接，即那些与信息序列的识别标签具有相同标签的序列。数据标签是由info函数添加到常规序列的，它们有效地编码了元数据键值对。（这意味着在传统 Prometheus 视图中，数据标签的更改构成了一个信息序列的结束和新信息序列的开始，而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])。但要从信息度量添加数据标签，用户必须使用复杂（且不甚明显）的语法来指定要使用的信息度量（target_info）、识别标签（on (job, instance)）以及要添加的数据标签（group_left (k8s_cluster_name)）。

此查询不仅冗长且难以编写，还可能陷入“身份危机”：如果target_info的任何数据标签发生更改，Prometheus 会将其视为序列的更改（如上所述，Prometheus 没有非识别标签的原生概念）。如果旧的target_info序列未正确标记为过时（某些摄取路径可能发生这种情况），则上述查询将失败长达 5 分钟（回溯增量），因为它会发现与旧版本和新版本target_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通常会自动查找所有匹配的信息序列，但可以通过提供__name__标签匹配器来限制它们，例如{__name__="target_info"}。

局限性

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

这些局限性在一定程度上削弱了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只应与计量器一起使用，并且只适用于浮点样本。范围向量中只包含直方图样本的元素会被完全忽略。对于包含浮点样本和直方图样本混合的元素，只使用浮点样本作为输入，这会通过信息级别注释进行标记。

`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): 指定间隔内最后一个样本的时间戳。

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

这些函数以以下方式作用于直方图

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

三角函数

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

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