查询函数 | Prometheus - Prometheus 监控系统

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

`abs()`

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

`absent()`

absent(v instant-vector) 如果传递给它的向量包含任何元素（浮点样本或直方图样本），则返回一个空向量；如果传递给它的向量不包含任何元素，则返回一个值等于 1 的 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 的 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 中包含范围内的浮点样本和直方图样本混合的每个元素将从结果向量中省略，并标记有警告级别（warn-level）的注释。

delta 仅应用于仪表（gauge）（浮点和直方图）。

`deriv()`

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

deriv 仅应用于仪表（gauge），且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点样本和直方图样本混合的元素，仅使用浮点样本作为输入，这会标记有信息级别（info-level）的注释。

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

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

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

`histogram_quantile()`

histogram_quantile(φ scalar, b instant-vector) 从经典直方图或原生直方图计算 φ-quantile (0 ≤ φ ≤ 1)。（有关 φ-quantiles 和经典直方图指标类型使用的详细说明，请参阅直方图和摘要。）

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() 函数会在分位数值所在的桶内插值计算分位数。对于经典直方图、具有自定义桶边界的原生直方图以及其他原生直方图的零桶，它假定桶内的观测值呈均匀分布（也称为线性插值）。对于具有标准指数分桶 schema 的非零桶的原生直方图，插值是在假设桶内样本的分布方式使得它们能够均匀填充具有更高分辨率的假想直方图。（这也称为指数插值。更多详细信息请参阅原生直方图规范。）

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

经典直方图的特殊情况

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

原生直方图的特殊情况（与零桶内发生的精确插值相关）

如果直方图在正值桶中有观测值，但在负值桶中没有，则假定具有有限宽度的零桶不包含负观测值。
如果直方图在负值桶中有观测值，但在正值桶中没有，则假定具有有限宽度的零桶不包含正观测值。

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

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

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

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

然而，浮点精度问题（例如，由 sum(rate(...)) 计算桶引入的小差异）或无效数据可能会违反这些假设。在这种情况下，histogram_quantile 将无法返回有意义的结果。为了解决这个问题，histogram_quantile 假定连续桶之间微小的相对差异是由于浮点精度错误造成的，并忽略它们。（忽略两个桶之间差异的阈值是两个桶总和的万亿分之一 (1e-12)。）此外，如果即使经过此调整后仍存在非单调的桶计数，它们将被增加到前一个桶的值以强制单调性。后者是输入数据存在实际问题的证据，因此会标记有信息级别（info-level）的注释，内容为 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 中最后两个样本中一个为浮点样本而另一个为直方图样本的元素将被从结果向量中省略，并标记有警告级别（warn-level）的注释。

idelta 仅应用于仪表（gauge）（浮点和直方图）。

`increase()`

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

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

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

increase 对直方图样本的作用是计算一个新的直方图，其中每个组成部分（观测值总和与计数、桶）是 v 中第一个和最后一个原生直方图相应组成部分之间的增长量。但是，v 中包含范围内浮点样本和直方图样本混合的每个元素将从结果向量中省略，并标记有警告级别（warn-level）的注释。

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

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

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 序列没有被正确标记为过期（这可能发生在某些 ingestion 路径中），上述查询可能会在长达 5 分钟（lookback delta）内失败，因为它会发现与新旧版本的 target_info 存在冲突匹配。

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

info 函数不仅解决了这个冲突，优先选择新的序列，还简化了语法，因为它知道可用的信息序列以及它们的识别性标签是什么。使用 info 函数的示例查询如下所示

info(rate(http_server_request_duration_seconds_count[2m]))

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

虽然 `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 中最后两个样本中一个为浮点样本而另一个为直方图样本的元素将从结果向量中省略，并标记有警告级别（warn-level）的注释。

irate 仅应用于计数器（counter）（浮点和直方图）。

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

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

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 对浮点和直方图样本的作用相同。

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

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

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 对浮点和直方图样本的作用相同。

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

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

第二个示例与第一个示例效果相同，并说明了命名捕获组的使用： `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` 仅应用于仪表（gauge），且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点样本和直方图样本混合的元素，仅使用浮点样本作为输入，这会标记有信息级别（info-level）的注释。

rate()

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

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

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

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

rate 仅应用于计数器（counter）（浮点和直方图）。它最适合用于告警和绘制变化缓慢的计数器。

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

resets()

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

resets 仅应用于计数器（counter）（浮点和直方图）。

浮点样本后跟直方图样本，或反之，算作一次重置。计数器直方图样本后跟仪表直方图样本，或反之，也算作一次重置（但请注意，`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` 相同，但按降序排序。

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

sort_by_label()

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

请注意，sort_by_label 仅影响即时查询的结果，因为范围查询结果始终具有固定的输出顺序。

`sort_by_label` 使用自然排序顺序。

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

sort_by_label_desc()

与 `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): 指定间隔内所有浮点样本的 φ-quantile (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): 指定间隔内所有浮点样本的中位数绝对偏差。

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

这些函数对直方图的作用如下
count_over_time, last_over_time, 和 present_over_time() 对浮点和直方图样本的作用相同。
avg_over_time() 和 sum_over_time() 对直方图样本的作用方式与相应的聚合运算符一致。如果一个序列在范围内包含浮点样本和直方图样本的混合，则相应的计算结果将完全从输出向量中移除。此类移除会标记有警告级别（warn-level）的注释。

所有其他函数按以下方式忽略直方图样本：仅包含直方图样本的输入范围会从输出中静默移除。对于包含直方图和浮点样本混合的范围，仅处理浮点样本，并标记有信息级别（info-level）的注释表示忽略了直方图样本。

三角函数

三角函数以弧度为单位工作。它们会忽略输入向量中的直方图样本。
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 中所有浮点样本的度数转换为弧度。

我们正在进行一项关于 Prometheus 中 OTLP 资源属性的调查，请参与！

函数

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

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

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

这些限制部分地损害了 info 函数的目的。在当前阶段，这是一个实验，旨在了解这种方法在实践中的有用程度。info 函数的最终版本将确实考虑所有匹配的信息序列及其适当的识别性标签。

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

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

第二个示例与第一个示例效果相同，并说明了命名捕获组的使用： label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P<name>.*):(?P<version>.*)")

ln(NaN) = NaN

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

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

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

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

predict_linear 仅应用于仪表（gauge），且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点样本和直方图样本混合的元素，仅使用浮点样本作为输入，这会标记有信息级别（info-level）的注释。

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

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

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

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

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

请注意，sort 仅影响即时查询的结果，因为范围查询结果始终具有固定的输出顺序。

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

sort_by_label 使用自然排序顺序。

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

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

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

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

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

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

所有其他函数按以下方式忽略直方图样本：仅包含直方图样本的输入范围会从输出中静默移除。对于包含直方图和浮点样本混合的范围，仅处理浮点样本，并标记有信息级别（info-level）的注释表示忽略了直方图样本。

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

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

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

这些限制部分地损害了 `info` 函数的目的。在当前阶段，这是一个实验，旨在了解这种方法在实践中的有用程度。`info` 函数的最终版本将确实考虑所有匹配的信息序列及其适当的识别性标签。

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

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

第二个示例与第一个示例效果相同，并说明了命名捕获组的使用： `label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P<name>.):(?P<version>.)")`

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

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

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

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

`predict_linear` 仅应用于仪表（gauge），且仅适用于浮点样本。范围向量中仅包含直方图样本的元素将被完全忽略。对于包含浮点样本和直方图样本混合的元素，仅使用浮点样本作为输入，这会标记有信息级别（info-level）的注释。

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

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

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

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

请注意，`sort` 仅影响即时查询的结果，因为范围查询结果始终具有固定的输出顺序。

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

`sort_by_label` 使用自然排序顺序。

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

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

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

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

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

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