函数

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

注意：关于实验性原生 Histogram：

• 要启用原生 Histogram 的消费，需要通过启用特性标志来实现。只要没有从 TSDB 中消费任何原生 Histogram ，所有函数的行为都将保持正常。
• 不在文档中明确提及支持原生 Histogram 的函数将忽略 Histogram 样本。
• 已支持处理原生 Histogram 的函数在未来可能会改变其行为。
• 如果一个函数需要多个由它处理的原生 Histogram 之间的相同桶布局，则 Prometheus 将自动适当地转换它们。（当前支持的桶模式始终可行。）

abs()

abs(v instant-vector)返回输入向量的所有样本值转换为其绝对值的新向量。

absent()

absent(v instant-vector)如果传入的向量包含任何元素（浮点数或原生 Histogram），则返回空向量；如果传入的向量没有任何元素，则返回一个值为 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)如果传入的范围向量包含任何元素（浮点数或原生 Histogram），则返回空向量；如果传入的范围向量没有任何元素，则返回一个值为 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)对v中所有元素的样本值向上取整到最接近且大于或等于 v 的整数值。

• 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)返回给定时间（UTC）的月份中的第几天。返回的值从1到31。

day_of_week()

day_of_week(v=vector(time()) instant-vector)返回给定时间（UTC）的星期几。返回的值从0到6，其中0表示周日等。

day_of_year()

day_of_year(v=vector(time()) instant-vector) 返回给定时间在 UTC 下的年中的第几天。返回值范围是从非闰年的1到365，闰年则是1到366。

days_in_month()

days_in_month(v=vector(time()) instant-vector)返回给定时间在 UTC 下的月份天数。返回值范围是从28到31。

delta()

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

以下示例表达式返回当前 CPU 温度与2小时前之差：

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

delta对于原生 Histogram 进行计算时，会创建一个新的 Histogram ，其中每个组件（观察总和，计数，桶）是第一个和最后一个原生 Histogram 在v中的相应组件的差值。然而，如果v中的元素包含范围内的混合浮点数和原生 Histogram 样本，则该元素的结果向量中将丢失。

delta只应与 Gauge 或行为如 Gauge 的原生 Histogram（所谓的“Gauge Histogram ”）一起使用。

deriv()

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

deriv只应与 Gauge 一起使用。

exp()

exp(v instant-vector)计算v中所有元素的指数函数。特殊情况如下：

• exp(+Inf) = +Inf
• exp(NaN) = NaN

floor()

floor(v instant-vector)将v中的所有元素的采样值向下取整到小于或等于v的最接近的整数值。

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

histogram_avg()

此函数仅作用于实验特性“原生 Histogram ”的 Histogram 。Prometheus 的未来版本中此函数的行为可能会改变，甚至可能从 PromQL 中移除。

histogram_avg(v instant-vector)返回存储在原生 Histogram 中的观察值的算术平均值。非原生 Histogram 的样本被忽略且不会出现在返回的向量中。

通过以下方式使用histogram_avg来计算5分钟窗口内从原生 Histogram 得出的请求持续时间平均值：

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 ”的 Histogram 。Prometheus的未来版本中这些函数的行为可能会改变，甚至可能从PromQL中移除。

histogram_count(v instant-vector)返回存储在原生 Histogram 中的观察值计数。非原生 Histogram 的样本被忽略且不会出现在返回的向量中。

同样地，histogram_sum(v instant-vector)返回存储在原生 Histogram 中的观察值之和。

使用histogram_count如下计算来自原生 Histogram 的“每秒请求次数”速率：

histogram_count(rate(http_request_duration_seconds[10m]))

histogram_fraction()

此函数仅作用于实验特性“原生 Histogram ”的 Histogram 。Prometheus 的未来版本中此函数的行为可能会改变，甚至可能从 PromQL 中移除。

对于原生 Histogram ，histogram_fraction(lower scalar, upper scalar, v instant-vector)返回在提供的较低和较高值之间的估计观察值比例。非原生 Histogram 的样本被忽略且不会出现在返回的向量中。

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

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

估计误差取决于底层原生 Histogram 的解析度以及提供的边界与 Histogram 桶边界的对齐程度。

+Inf和-Inf是有效的边界值。例如，如果表达式中的 Histogram 包括负观察值（这不应该发生在请求持续时间上），则将所有小于或等于0.2的观察值包括在内的适当下界应该是-Inf而不是0。

提供边界是否包含还是排除只在边界与底层 Histogram 中正值的桶边界精确对齐时才相关。在这种情况下，行为取决于 Histogram 的定义。目前支持的所有定义都具有包含正值的上边界和排除的下边界，并且反之亦然适用于负值。没有精确对齐的边界，函数使用线性插值来估算比例。由于由此产生的不确定性，边界是否包含或排除变得无关紧要。

histogram_quantile()

histogram_quantile(φ scalar, b instant-vector)计算来自经典 Histogram 或原生 Histogram 的 φ-分位数（0 ≤ φ ≤ 1）。(有关 φ-分位数和经典 Histogram 指标类型一般用法的详细解释，请参阅 Histogram 与 Summary)

请注意，原生 Histogram 是一个实验特性。在 Prometheus 的未来版本中，处理原生 Histogram 时此函数的行为可能会改变。

b中的浮点样本被视为一个或多个经典 Histogram 的每个桶中观测的数量。每个浮点样本必须具有一个标签le，其中标签值表示桶的上限。不带le标签的浮点样本会被忽略。其他标签和指标名称用于识别属于每个经典 Histogram 的桶。Histogram 指标类型自动提供带有_bucket后缀以及适当标签的时间序列。

对于原生 Histogram 样本，它们被分别视为单独的 Histogram 来计算分位数。

只要没有命名冲突产生，b可以包含经典和原生 Histogram 的混合。

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

示例：一个名为http_request_duration_seconds的指标（因此经典 Histogram 的桶名是http_request_duration_seconds_bucket）。要计算过去10分钟内请求持续时间的90%分位数，当http_request_duration_seconds是经典 Histogram 时，可以使用以下表达式：

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

对于原生 Histogram ，使用以下表达式代替：

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

对于经典 Histogram ，聚合90%分位数时，使用sum()聚合器包含rate()函数。由于histogram_quantile()需要处理经典 Histogram 时需要le标签，它必须包含在by子句中。对于经典 Histogram ，以下表达式按job聚合90%分位数：

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

对于原生 Histogram 的聚合，表达式简化为：

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

要聚合所有经典 Histogram ，只需指定le标签：

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

对于原生 Histogram ，聚合所有内容通常无需任何by子句：

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

histogram_quantile()函数通过假设桶内的分布线性分布来插值分位数值。

如果b包含零观测，则返回NaN。对于 φ < 0，返回-Inf。对于 φ > 1，返回+Inf。对于 φ = NaN，返回NaN。

对于经典 Histogram 而言，仅在以下情况下才总是成立：

• 桶中的计数单调递增（严格非递减）。
• 连续桶之间观测缺失导致这些两个桶的计数相等。

然而，浮点精度问题（例如，由 sum(rate(...)) 计算桶时引入的小差异）或无效数据可能违反这些假设。在这种情况下，histogram_quantile将无法返回有意义的结果。为了缓解这个问题，histogram_quantile假设连续桶之间极小的相对差异是因为浮点精度错误并忽略它们。（忽略两个桶之间差异的阈值是两桶之和的十万亿分之一（1e-12））。此外，如果在进行这种调整后仍存在非单调桶计数，则会增加到前一个桶的值以确保单调性。后者对应输入数据存在问题的情况，此时，将会标记内容为input to histogram_quantile needed to be fixed for monotonicity的信息类注释。如果你遇到此注释，应找到并移除无效数据的来源。

histogram_stddev()和histogram_stdvar()

这两个函数仅适用于实验功能中的原生 Histogram 。Prometheus 的未来版本中这些函数的行为可能会改变，包括从PromQL中移除它们的可能性。

histogram_stddev(v instant-vector)根据直方桶中观测值的几何平均值，返回原生 Histogram 中观测值的估计标准差。非原生 Histogram 的样本将被忽略，并不会出现在返回的向量中。

同样地，histogram_stdvar(v instant-vector)返回原生 Histogram 中观测值的估计标准方差。

holt_winters()

holt_winters(v range-vector, sf scalar, tf scalar)根据范围在v中的时间序列生成平滑值。平滑因子sf的值越低，表示赋予较旧数据的重要性越高。趋势因子tf的值越高，则认为数据中的趋势越明显。sf和tf都必须在0和1之间。

holt_winters只应该与 Gauge 一起使用。

hour()

hour(v=vector(time()) instant-vector)对给定的 UTC 时间的每个时间点返回一天中的小时数。返回的值范围是0到23。

idelta()

idelta(v range-vector)计算范围向量v中的最后两个样本之间的差异，返回包含给定差值和等效标签的瞬时向量。

idelta应该只与 Gauge 一起使用。

increase()

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

以下示例表达式返回过去5分钟内测量的 HTTP 请求次数，对于范围向量中的每一项时间序列：

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

increase在原生 Histogram 上工作，通过计算第一个和最后一个原生 Histogram 在v中的组件（观测值的总和和计数、桶）之间的增长来创建一个新的 Histogram 。然而，如果v中的元素包含范围内的浮点数和原生 Histogram 样本的混合，则结果向量将缺少这些元素。

increase应该只用于 Counter 和原生 Histogram（组件行为类似于 Counter）。它是在指定时间窗口内，rate(v)乘以秒数的语法糖，主要用于增强可读性。在记录规则中使用rate确保增长在每秒都能被持续追踪。

irate()

irate(v range-vector)计算范围向量v中的时间序列每秒的瞬时增长率，这是基于最后两个数据点的。它自动调整因目标重启导致的单调性中断。

以下示例表达式返回过去5分钟内对于最近两个数据点的 HTTP 请求速率，对于范围向量中的每一项时间序列：

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

irate应该在绘制快速移动的 Counter 时使用。对于告警和缓慢移动的 Counter ，使用rate更合适，因为速率的变化可能重置FOR子句，得到难以阅读的全由尖峰组成的图表。

请注意，当结合irate()与聚合运算符（例如 sum()）或在时间上进行聚合的函数（任何以 _over_time 结尾的函数）时，总是先进行 irate()，然后进行聚合。否则，irate()将无法检测目标重启时的 Counter 重置。

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对于浮点数和 Histogram 样本也是如此作用。

以下示例将返回一个向量，其中每个时间序列都有一个 foo 标签，其值为 a,b,c：

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对于浮点数和 Histogram 样本也是相同的作用。

以下示例将返回具有值a:c的service标签和 a的foo标签的时间序列：

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)对给定的UTC时间的每个时间点返回小时中的分钟数。返回的值范围是从0到59。

month()

month(v=vector(time()) instant-vector)对给定的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)计算时间序列在范围向量中的每秒平均增加速率。会自动调整由于目标重启导致的单调性中断（如 Counter 重置）。此外，此计算还会外推到时间范围的两端，支持抓取丢失或抓取周期与范围的时间段不完美对齐的情况。

以下示例表达式返回过去5分钟内每个时间序列的 HTTP 请求每秒速率：

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

rate对原生 Histogram 进行操作时，通过计算新的 Histogram ，其中每个组件（观测总和和计数，桶）是第一个和最后一个原生 Histogram 之间的增加速率。然而，如果范围内的v包含混合浮点数和原生 Histogram 样本，则结果向量中将缺少这些元素。

rate只应与行为类似于 Counter 的 Counter 和原生 Histogram 一起使用。它最适合用于告警，并适合缓慢移动 Counter 的图形显示。

请注意，在与聚合操作符（例如 sum()）结合使用或在时间上进行函数聚合（任何以_over_time结尾的函数）时，请始终先使用rate()，然后再进行聚合。否则，当你的目标重启时，rate()无法检测到 Counter 重置。

resets()

对于输入的每个时间序列，resets(v range-vector)返回提供的时间范围内 Counter 重置的数量作为瞬时向量。两次连续浮点样本值之间的减少被解释为 Counter 重置。对于原生 Histogram 的重置检测更为复杂：任何桶（包括零桶）中的减少，或观测计数的减少，都构成 Counter 重置。但先前已填充的桶消失、桶解析度增加或零桶宽度减少等情况也会造成重置。

resets只应与 Counter 和类似 Counter 的原生 Histogram 一起使用。

如果范围向量包含同一系列中的混合浮点和 Histogram 样本，则单独检测 Counter 重置并累加其数量。从浮点到 Histogram 样本的变化不被视为 Counter 重置。每次比较一个浮点样本与下一个浮点样本，每个 Histogram 与下一个 Histogram 进行比较。

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)返回排序后的向量元素，根据其样本值按升序排列。原生 Histogram 按观测总和排序。

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

sort_desc()

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

如同sort，sort_desc只影响即时查询的结果，因为范围查询结果始终具有固定的输出顺序。

sort_by_label()

特性标志启用说明

此函数需要通过特性标志--enable-feature=promql-experimental-functions启用。

sort_by_label(v instant-vector, label string, ...)函数按照给定标签的值进行升序排序返回向量元素。如果这些标签值相同，则根据它们的完整标签集对元素进行排序。

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

此函数使用了自然排序规则。

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 至今的秒数。它也适用于 Histogram 样本。

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): 指定区间内所有点的中位绝对偏差。

请注意，指定区间的所有值在聚合中都具有相同的权重，即使这些值在整个区间内不是等距分布的。

avg_over_time、sum_over_time、count_over_time、last_over_time和present_over_time对原生 Histogram 处理得当。其他所有函数忽略 Histogram 样本。

三角函数

三角函数采用弧度制：

• 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(): 返回π。
• rad(v instant-vector): 将度数转换为弧度，适用于v中的所有元素。

该文档基于 Prometheus 官方文档翻译而成。