全部产品

函数参考

更新时间:2019-06-29 05:33:31

函数参考

一些函数有默认的参数,例如:year(v=vector(time()) instant-vector)。v是参数值,instant-vector是参数类型。vector(time())是默认值。

  • abs()

abs(v instant-vector)返回输入向量中所有样本的绝对值。

  • absent()

absent(v instant-vector),如果输入向量中具有样本数据,则返回空向量;如果传递的瞬时向量中没有样本数据,则返回不带度量指标名称且带有标签的样本值为1的结果
当监控度量指标时,如果获取到的样本数据是空的, 使用absent方法对告警是非常有用的

  1. absent(nonexistent{job="myjob"})
  2. # => {job="myjob"}
  3. absent(nonexistent{job="myjob",instance=~".*"})
  4. # => {job="myjob"}
  5. absent(sum(nonexistent{job="myjob"}))
  6. # => {}

在第二个例子中, absent() 试图从输入向量中导出单元素输出向量的标签。

  • ceil()

ceil(v instant-vector) 向上舍入为最接近的整数。

  • changes()

changes(v range-vector) 输入一个区间向量, 返回这个区间向量内每个样本数据值变化的次数。

  • clamp_max()

clamp_max(v instant-vector, max scalar)输入一个瞬时向量和最大值,样本数据值若大于max,则改为max,否则不变。

  • clamp_min()

clamp_min(v instant-vector)输入一个瞬时向量和最大值,样本数据值小于min,则改为min。否则不变

  • count_saclar()

count_scalar(v instant-vector) 输入一个瞬时向量,返回(key:value)=(”scalar”: 样本个数)。而count()函数,输入一个瞬时向量,返回(key:value)=(向量:样本个数),其中结果中的向量允许通过by条件分组。

  • 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)返回当月一共有多少天。返回值范围:28~31.

  • delta()

delta(v range-vector)的参数是一个区间向量,返回一个瞬时向量。它计算一个区间向量 v 的第一个元素和最后一个元素之间的差值。由于这个值被外推到指定的整个时间范围,所以即使样本值都是整数,你仍然可能会得到一个非整数值。
例如,下面的例子返回过去两小时的 CPU 温度差:

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

这个函数一般只用在 Gauge 类型的时间序列上。

  • deriv()

deriv(v range-vector)计算一个区间向量v中各个时间序列二阶导数,使用简单线性回归
deriv二阶导数返回值类型只能是gauges。

  • exp()

exp(v instant-vector)输入一个瞬时向量, 返回各个样本值的e指数值,即为e的N次方。特殊情况如下所示:

  1. Exp(+ Inf)= + Inf
  2. Exp(NaN)= NaN
  • floor()

floor(v instant-vector)函数与 ceil() 函数相反,将 v 中所有元素的样本值向下四舍五入到最接近的整数。

  • histogram_quantile()

histogram_quantile(φ float, b instant-vector) 从 bucket 类型的向量 b 中计算 φ (0 ≤ φ ≤ 1) 分位数(百分位数的一般形式)的样本的最大值。(有关 φ 分位数的详细说明以及直方图指标类型的使用,请参阅直方图和摘要)。向量 b 中的样本是每个 bucket 的采样点数量。每个样本的 labels 中必须要有 le 这个 label 来表示每个 bucket 的上边界,没有 le 标签的样本会被忽略。直方图指标类型自动提供带有 _bucket 后缀和相应标签的时间序列。
可以使用 rate() 函数来指定分位数计算的时间窗口。
例如,一个直方图指标名称为 employee_age_bucket_bucket,要计算过去 10 分钟内 第 90 个百分位数,请使用以下表达式:

  1. histogram_quantile(0.9, rate(employee_age_bucket_bucket[10m]))

返回:

  1. {instance="10.0.86.71:8080",job="prometheus"} 35.714285714285715

这表示最近 10 分钟之内 90% 的样本的最大值为 35.714285714285715。
这个计算结果是每组标签组合成一个时间序列。我们可能不会对所有这些维度(如 jobinstancemethod)感兴趣,并希望将其中的一些维度进行聚合,则可以使用 sum() 函数。例如,以下表达式根据 job 标签来对第 90 个百分位数进行聚合:

  1. # histogram_quantile() 函数必须包含 le 标签
  2. histogram_quantile(0.9, sum(rate(employee_age_bucket_bucket[10m])) by (job, le))

如果要聚合所有的标签,则使用如下表达式:

  1. histogram_quantile(0.9,sum(rate(employee_age_bucket_bucket[10m])) by (le))

注意:
histogram_quantile 这个函数是根据假定每个区间内的样本分布是线性分布来计算结果值的(也就是说它的结果未必准确),最高的 bucket 必须是 le=”+Inf” (否则就返回 NaN)。
如果分位数位于最高的 bucket(+Inf) 中,则返回第二个最高的 bucket 的上边界。如果该 bucket 的上边界大于 0,则假设最低的 bucket 的的下边界为 0,这种情况下在该 bucket 内使用常规的线性插值。
如果分位数位于最低的 bucket 中,则返回最低 bucket 的上边界。

  • holt_winters()

holt_winters(v range-vector, sf scalar, tf scalar)基于区间向量v,生成事件序列数据平滑值。平滑因子sf越低, 对老数据越重要。趋势因子tf越高,越多的数据趋势应该被重视0<sf,tf<=1。 holt_winters仅用于gauges。

  • hour()

hour(v=vector(time()) instant-vector)返回给定UTC时间的当前第几个小时,时间范围:0~23。

  • idelta()

idelta(v range-vector)输入一个区间向量,返回(key: value )=( 度量指标: 每最后两个样本值差值)。

  • increase()

increase(v range-vector)输入一个区间向量,返回:(key:value) = (度量指标:last值-first值),自动调整单调性,如:服务实例重启,则计数器重置。与delta()不同之处在于delta是求差值,而increase返回最后一个减第一个值,可正可负。
下面的表达式例子,返回过去5分钟,连续两个时间序列数据样本值的http请求增加值。

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

increase的返回值类型只能是counters类型,主要作用是增加图表和数据的可读性,使用rate记录规则的使用率,以便持续跟踪数据样本值的变化。

  • irate()

irate(v range-vector) 函数用于计算区间向量的增长率,但是其反应出的是瞬时增长率。irate 函数是通过区间向量中最后两个两本数据来计算区间向量的增长速率,它会在单调性发生变化时(如由于采样目标重启引起的计数器复位)自动中断。这种方式可以避免在时间窗口范围内的“长尾问题”,并且体现出更好的灵敏度,通过irate函数绘制的图标能够更好的反应样本数据的瞬时变化状态。
例如,以下表达式返回区间向量中每个时间序列过去 5 分钟内最后两个样本数据的 HTTP 请求数的增长率:

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

irate只能用于绘制快速移动的计数器。在长期趋势分析或者告警中更推荐使用 rate 函数。因为使用 irate 函数时,速率的简短变化会重置 FOR语句,形成的图形有很多波峰,难以阅读。
注意:
当将 irate() 函数与聚合运算符(例如 sum())或随时间聚合的函数(任何以 _over_time 结尾的函数)一起使用时,必须先执行 irate 函数,然后再进行聚合操作,否则当采样目标重新启动时 irate() 无法检测到计数器是否被重置。

  • label_join()
    1. label_join(up{job="api-server",src1="a",src2="b",src3="c"}, "foo", ",", "src1", "src2", "src3")
    函数可以将时间序列 v 中多个标签 src_label 的值,通过 separator 作为连接符写入到一个新的标签 dst_label 中。可以有多个 src_label 标签。
    例如,以下表达式返回的时间序列多了一个 foo 标签,标签值为 etcd,etcd-k8s
  1. up{endpoint="api",instance="192.168.123.248:2379",job="etcd",namespace="monitoring",service="etcd-k8s"}
  2. => up{endpoint="api",instance="192.168.123.248:2379",job="etcd",namespace="monitoring",service="etcd-k8s"} 1
  3. label_join(up{endpoint="api",instance="192.168.123.248:2379",job="etcd",namespace="monitoring",service="etcd-k8s"}, "foo", ",", "job", "service")
  4. => up{endpoint="api",foo="etcd,etcd-k8s",instance="192.168.123.248:2379",job="etcd",namespace="monitoring",service="etcd-k8s"} 1
  5. label_replace()
  • label_replace()

对于v中的每个时间序列,label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string) 将正则表达式与标签值src_label匹配。如果匹配,则返回时间序列,标签值dst_label被替换的扩展替换。$1替换为第一个匹配子组,$2替换为第二个等。如果正则表达式不匹配,则时间序列不会更改。
另一种更容易的理解是:label_replace函数,输入:瞬时向量,输出:(key: value) = (度量指标: 值(要替换的内容))。首先,针对src_label标签,对该标签值进行regex正则表达式匹配。如果不能匹配的度量指标,则不发生任何改变;否则,把dst_label标签的标签纸替换为replacement 下面这个例子返回一个向量值a带有foo标签:

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

ln(v instance-vector)计算瞬时向量v中所有样本数据的自然对数。特殊情况:

  • ln(+Inf) = +Inf
  • ln(0) = -Inf
  • ln(x < 0) = NaN
  • ln(NaN) = NaN

  • log2()

log2(v instant-vector)函数计算瞬时向量v中所有样本数据以2为底的对数。特殊情况同上。

  • log10()

log10(v instant-vector)函数计算瞬时向量v中所有样本数据以10为底的对数。相当于ln()。特殊情况同上。

  • minute()

minute(v=vector(time()) instant-vector)返回给定UTC时间当前小时的第多少分钟。结果范围:0~59。

  • month()

month(v=vector(time()) instant-vector)返回给定UTC时间当前属于第几个月,结果范围:0~12。

  • predict_linear()

predict_linear(v range-vector,t scalar) 使用简单线性回归,基于区间向量v预测从现在开始的时间序列t秒后的值。predict_linear 仅适用于gauges。

  • rate()

rate(v range-vector) 可以直接计算区间向量 v 在时间窗口内平均增长速率,它会在单调性发生变化时(如由于采样目标重启引起的计数器复位)自动中断。该函数的返回结果不带有度量指标,只有标签列表。
以下示例表达式返回区间向量中每个时间系列在过去5分钟内测量的每秒HTTP请求率:

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

rate应仅用于counters。在长期趋势分析或者告警中推荐使用这个函数。
注意,当将rate()与聚合运算符(例如sum())或随时间聚合的函数(任何以_over_time结尾的函数)组合时,始终首先采用rate(),然后聚合。否则,当目标重新启动时,rate()无法检测计数器重置。

  • resets()

对于每个输入时间序列,复位(v range-vector)将提供的时间范围内的计数器复位数作为即时向量返回。两个连续样本之间的值的任何减少都被解释为计数器重置。
resets只与counters一起使用。

  • round()

round(v instant-vector, to_nearest=1 scalar) 函数与 ceil 和 floor 函数类似,返回向量中所有样本值的最接近的整数。to_nearest 参数是可选的,默认为 1,表示样本返回的是最接近 1 的整数倍的值。你也可以将该参数指定为任意值(也可以是小数),表示样本返回的是最接近它的整数倍的值。

  • scalar()

scalar(v instant-vector) 函数的参数是一个单元素的瞬时向量,它返回其唯一的时间序列的值作为一个标量。如果度量指标的样本数量大于 1 或者等于 0, 则返回 NaN

  • sort()

sort(v instant-vector) 函数对向量按元素的值进行升序排序,返回结果:key: value = 度量指标:样本值[升序排列]。

  • sort_desc()

sort(v instant-vector) 函数对向量按元素的值进行降序排序,返回结果:key: value = 度量指标:样本值[降序排列]。

  • sqrt()

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

  • time()

time() 函数返回从 1970-01-01 到现在的秒数。注意:它不是直接返回当前时间,而是时间戳。

  • timestamp()

timestamp(v instant-vector)返回给定向量的每个样本的时间戳,作为自1970年1月1日UTC以来的秒数。
此功能已添加到Prometheus 2.0中。

  • vector()

vector(s scalar)函数,返回:(key: value)= ({}, 传入参数值)。

  • year()

year(v = vector(time())instant-vector)返回UTC中每个给定时间的年份。
_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): 区间向量内每个度量指标的总体标准方差。

注意:
即使区间向量内的值分布不均匀,它们在聚合时的权重也是相同的。