运维监控系列（21）-PromQL内置函数

曾经终败给现在 2023-10-09 13:31 55阅读 0赞

### 函数 ###

某些函数具有默认参数，例如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)将所有元素的样本值v向上舍入到最接近的整数。

### changes() ###

对于每个输入时间序列，changes(v range-vector)返回其值在提供的时间范围内作为即时向量发生变化的次数。

### clamp() ###

clamp(v instant-vector, min scalar, max scalar) 将所有元素的样本值钳制在v下限为min和上限为max。

特殊情况： - 返回空向量 if min > max - 返回NaNifmin或maxisNaN

### 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 表示星期日等。

### days\_in\_month() ###

days\_in\_month(v=vector(time()) instant-vector)返回每个给定时间的 UTC 月份中的天数。返回值是从 28 到 31。

### delta() ###

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

以下示例表达式返回现在和 2 小时前之间 CPU 温度的差异：

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

delta 只能与仪表一起使用。

### deriv() ###

deriv(v range-vector)v使用简单线性回归计算范围向量中时间序列的每秒导数。

deriv 只能与仪表一起使用。

### exp() ###

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

*  Exp(+Inf) = +Inf
 *  Exp(NaN) = NaN

### floor() ###

floor(v instant-vector)将所有元素的样本值v向下舍入到最接近的整数。

### histogram\_quantile() ###

histogram\_quantile(φ scalar, b instant-vector)从直方图的桶b中 计算 φ-分位数 (0 ≤ φ ≤ 1) 。（有关φ 分位数的详细说明和直方图度量类型的一般用法，请参阅 直方图和摘要。）中的样本是每个桶中的观察计数。每个样本必须有一个标签，其中标签值表示桶的包含上限。（没有这种标签的样本将被默默忽略。）直方图度量类型 自动提供带有后缀和适当标签的时间序列。ble\_bucket使用该rate()函数指定分位数计算的时间窗口。

示例：直方图度量称为http\_request\_duration\_seconds。要计算过去 10m 中请求持续时间的第 90 个百分位数，请使用以下表达式：

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

分位数是为 中的每个标签组合计算的 http\_request\_duration\_seconds。要聚合，请sum()在rate()函数周围使用聚合器。由于le需要标签 histogram\_quantile()，因此它必须包含在by子句中。以下表达式将第 90 个百分位数聚合为job：

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

要聚合所有内容，请仅指定标签：

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

该histogram\_quantile()函数通过假设桶内的线性分布来插入分位数值。最高存储桶的上限必须为+Inf。（否则，NaN返回。）如果分位数位于最高桶中，则返回第二高桶的上限。如果最低桶的上限大于 0，则假定最低桶的下限为 0。在这种情况下，在该桶内应用通常的线性插值。否则，为位于最低存储桶中的分位数返回最低存储桶的上限。

如果b有 0 个观察值，NaN则返回。如果b包含少于两个桶， NaN则返回。对于 φ < 0，-Inf返回。对于 φ > 1，+Inf返回。

### holt\_winters() ###

holt\_winters(v range-vector, sf scalar, tf scalar)根据 中的范围为时间序列生成平滑值v。平滑因子越低sf，旧数据就越重要。趋势因子越高tf，数据中的趋势被考虑的越多。二者sf并tf必须在0和1之间。

holt\_winters 只能与仪表一起使用。

### hour() ###

hour(v=vector(time()) instant-vector)以 UTC 格式返回每个给定时间的一天中的小时。返回值从 0 到 23。

### idelta() ###

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

idelta 只能与仪表一起使用。

### increase() ###

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

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

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

increase应该只与计数器一起使用。它是rate(v)乘以指定时间范围窗口下的秒数的语法糖，主要用于人类可读性。rate在记录规则中使用，以便每秒一致地跟踪增加。

### irate() ###

irate(v range-vector)计算范围向量中时间序列的每秒即时增长率。这是基于最后两个数据点。单调性中断（例如由于目标重新启动引起的计数器重置）会自动调整。

以下示例表达式返回范围向量中每个时间序列的两个最近数据点的 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, …)连接所有src\_labels using的所有值separator并返回带有dst\_label包含连接值的标签的时间序列。src\_labels在这个函数中可以有任意数量的。

此示例将返回一个向量，其中每个时间序列都有一个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等引用。如果正则表达式不匹配，则返回时间序列不变。

此示例将返回带有a:clabelservice和alabel 处值的时间序列foo：

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

### 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)t基于范围向量v，使用简单线性回归预测从现在开始的时间序列秒的值 。

predict\_linear 只能与仪表一起使用。

### rate() ###

rate(v range-vector)计算范围向量中时间序列的每秒平均增长率。单调性中断（例如由于目标重新启动引起的计数器重置）会自动调整。此外，计算外推到时间范围的末端，允许遗漏刮擦或刮擦周期与范围时间段的不完美对齐。

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

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

rate应该只与计数器一起使用。它最适合用于警报和缓慢移动计数器的图形。

请注意，当rate()与聚合运算符（例如sum()）或随时间聚合的函数（以 结尾的任何函数\_over\_time）组合时，始终rate()先进行聚合，然后进行聚合。否则rate()当您的目标重新启动时无法检测计数器重置。

### resets() ###

对于每个输入时间序列，resets(v range-vector)返回提供的时间范围内的计数器重置次数作为即时向量。两个连续样本之间的任何值减少都被解释为计数器重置。

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\_desc() ###

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

### sqrt() ###

sqrt(v instant-vector)计算 中所有元素的平方根v。

### time() ###

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

### timestamp() ###

timestamp(v instant-vector) 返回给定向量的每个样本的时间戳，作为自 UTC 时间 1970 年 1 月 1 日以来的秒数。

这个功能是在 Prometheus 2.0 中添加的

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

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

### 文档来源 ###

https://prometheus.io/docs/prometheus/latest/querying/operators/