查询函数

有些函数有默认参数，例如 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 中的浮点数样本解释为时间戳（自 UTC 1970 年 1 月 1 日以来的秒数），并返回每个时间戳的月份中的日期（以 UTC 为准）。返回值范围为 1 到 31。输入向量中的直方图样本会被静默忽略。

`day_of_week()`

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

`day_of_year()`

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

`days_in_month()`

days_in_month(v=vector(time()) instant-vector) 将 v 中的浮点数样本解释为时间戳（自 UTC 1970 年 1 月 1 日以来的秒数），并返回每个时间戳所在月份的天数（以 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 中的浮点数样本解释为时间戳（自 UTC 1970 年 1 月 1 日以来的秒数），并返回每个时间戳的一天中的小时（以 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 metrics）的标签时的用户体验。此函数的行为在 Prometheus 的未来版本中可能会发生变化，甚至可能从 PromQL 中移除。info 必须通过功能标志 --enable-feature=promql-experimental-functions 来启用。

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

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

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

  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 序列没有被正确标记为过时（stale）（这在某些数据采集路径下可能发生），上述查询将在长达 5 分钟（lookback delta）的时间内失败，因为它会发现与新旧两个版本的 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, ...) 将所有 src_labels 的值使用 separator 连接起来，并返回带有包含连接后值的 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 中的浮点数样本解释为时间戳（自 UTC 1970 年 1 月 1 日以来的秒数），并为每个时间戳返回小时中的分钟数（UTC 时间）。返回值为 0 到 59。输入向量中的直方图样本将被静默忽略。

`month()`

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

`predict_linear()`

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

predict_linear 只应与 gauge 指标一起使用，并且只对浮点数样本有效。范围向量中仅包含直方图样本的元素将被完全忽略。对于同时包含浮点数和直方图样本的元素，只有浮点数样本被用作输入，并会附带一个信息级别的注解。

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

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

一个浮点数样本后跟一个直方图样本，或者反之，都算作一次重置。一个计数器直方图样本后跟一个 gauge 直方图样本，或者反之，也算作一次重置（但请注意，如上所述，resets 首先就不应该用于 gauge 指标）。

`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() 返回自 UTC 1970 年 1 月 1 日以来的秒数。请注意，这实际上返回的不是当前时间，而是表达式将被评估的时间。

`timestamp()`

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

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