Prometheus PromQL 查询函数完全参考签名、语义与源码实现【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheusPromQLPrometheus Query Language内置了大量查询函数覆盖数学运算、计数器速率、直方图分析、时间日期、标签改写等场景是编写告警规则与仪表盘表达式的核心工具。本文以仓库内的 PromQL 函数官方文档 为骨架逐组讲解每个函数的签名、语义、边界情况与经典用例并结合 promql/functions.go 等源码说明底层实现与注解行为。读完本文你将能够准确选用函数、理解函数对浮点样本与本机直方图样本的不同处理方式并掌握实验性函数的启用方法。阅读前必须理解的三条通用约定在使用任何 PromQL 函数前需要先建立三个全局观念它们贯穿下面所有函数的行为描述。默认参数部分函数带有默认实参例如year(vvector(time()) instant-vector)含义是函数有一个 instant-vector瞬时向量类型的参数v当调用时未显式提供时它自动默认取表达式vector(time())的求值结果。同类的时间/日期函数如hour()、month()都遵循这一约定。瞬时向量与区间向量参数类型标注为instant-vector的函数通常作用在某一刻的一组样本上标注为range-vector区间向量通常写作metric[5m]的函数则作用在时间窗口内的全部样本上用于计算速率、增量或随时间聚合。浮点样本与本机直方图样本Prometheus 时间序列可以同时承载 float浮点样本和 native histogram本机直方图样本。绝大多数函数对浮点样本运算时会静默忽略直方图样本而速率/增量类函数与histogram_*系列则专门针对直方图语义做了定义。个别函数对“区间内同时出现浮点与直方图样本”的情况会丢弃对应序列并以 warn/info 级注解annotation提示——这一点是理解许多“奇怪行为”的关键在文末的源码剖析中会展开。有关聚合操作符、正则表达式匹配等基础语法可参考 聚合操作符 与 正则表达式。数学与取整函数abs(v instant-vector)返回输入向量中所有浮点样本的绝对值。直方图样本被静默忽略。ceil(v instant-vector)与floor(v instant-vector)ceil向上取整到不小于原值的最小整数floor向下取整到不大于原值的最大整数。两者都静默忽略直方图样本并遵循 IEEE-754 特例ceil(Inf) Inf、ceil(±0) ±0、ceil(1.49) 2.0、ceil(1.78) 2.0floor(Inf) Inf、floor(±0) ±0、floor(1.49) 1.0、floor(1.78) 1.0round(v instant-vector, to_nearest1 scalar)把所有样本值四舍五入到最近的整数平局恰好在中间时向上取整。可选参数to_nearest指定取整的“步长”即样本值需要舍入到的最近倍数该倍数也可以是小数例如round(http_requests_total / 1000, 10) # 以 10 为单位取整直方图样本被静默忽略。clamp()、clamp_max()与clamp_min()clamp(v instant-vector, min scalar, max scalar)把样本值限制在[min, max]区间内。clamp_max(v instant-vector, max scalar)只设置上限。clamp_min(v instant-vector, min scalar)只设置下限。三者的边界特例如下clamp若min max返回空向量若min或max为NaN返回NaN若min为-Inf且max为Inf浮点样本原样保留。clamp_maxmax为NaN时返回NaNmax为Inf时样本不变max为-Inf时所有浮点样本都被设为-Inf。clamp_minmin为NaN时返回NaNmin为-Inf时样本不变min为Inf时所有浮点样本都被设为Inf。三个函数都静默忽略直方图样本。在源码 promql/functions.go 中它们统一由clamp(vec, minVal, maxVal, enh)辅助函数及funcClamp/funcClampMax/funcClampMin三个入口实现。对数与指数exp(v instant-vector)对每个浮点样本计算自然指数。特例Exp(Inf) Inf、Exp(NaN) NaN。ln(v instant-vector)自然对数。特例ln(Inf) Inf、ln(0) -Inf、ln(x0) NaN、ln(NaN) NaN。log2(v instant-vector)以 2 为底的对数特例与ln一致。log10(v instant-vector)以 10 为底的对数特例与ln一致。sqrt(v instant-vector)平方根。以上函数均静默忽略直方图样本。sgn(v instant-vector)返回样本值的符号值为正返回1为负返回-1等于零返回0。直方图样本被静默忽略。scalar(v instant-vector)与vector(s scalar)scalar若输入向量恰好只有一个含浮点样本的元素返回该样本值作为标量否则返回NaN。直方图样本被静默忽略。vector将标量s包装成一个无标签的单元素瞬时向量。这一对函数常用于“标量与向量混用”的表达式拼接。时间与日期函数无参时钟类time()返回自 1970-01-01 UTC 以来的秒数。注意它返回的不是“当前真实时间”而是该表达式被求值的时间点即查询评估时间。在源码中它由 promql/functions.go 的funcTime实现。timestamp(v instant-vector)返回输入向量中每个样本自身的时间戳自 Unix epoch 起的秒数对浮点与直方图样本一视同仁。start_timestamp(v instant-vector)返回给定向量每个样本的起始时间戳。注意它只作用于直接传入的瞬时向量且必须开启--enable-featureuse-start-timestamps若作用于普通表达式或未开启该特性则返回空结果。日期分解类UTC均默认参数vvector(time())这一组函数把样本值当作时间戳自 1970-01-01 UTC 的秒数在 UTC 时区内分解并返回对应字段函数返回值范围含义year(vvector(time()))年份返回给定时间的年份month(vvector(time()))1–12月份1 表示一月day_of_month(vvector(time()))1–31当月第几日day_of_week(vvector(time()))0–6星期几0 表示周日day_of_year(vvector(time()))1–365闰年 366当年第几日days_in_month(vvector(time()))28–31当月天数hour(vvector(time()))0–23当日第几小时minute(vvector(time()))0–59小时内第几分钟它们全部静默忽略直方图样本。由于这类函数的结果依赖求值时间days_in_month、day_of_month、day_of_week、day_of_year、hour、minute、month、year、time、predict_linear等都被列入源码中的AtModifierUnsafeFunctionspromql/functions.go意味着它们与修饰符组合时可能不安全。查询上下文类实验性以下函数把“当前查询上下文”暴露为标量秒数必须在启用promql-experimental-functions特性后可用start()返回当前 range query范围查询评估的起始时间戳对瞬时查询等价于评估时间戳。end()返回当前 range query 评估的结束时间戳对瞬时查询等价于评估时间戳。step()返回当前查询的分辨率步长秒数对瞬时查询返回0。range()返回当前 range query 的时间跨度秒数等价于end() - start()对瞬时查询返回0。从源码看这四者在FunctionCalls注册表中的实现均为nil注释标明它们会被foldQueryContextFunctions折叠为 NumberLiteralpromql/functions.go也就是说它们在语法分析/常量折叠阶段就被转换成具体数字而非运行时求值。计数器、速率与增量函数这一组是 PromQL 最核心的函数族全部要求range-vector输入。理解它们的公共点很重要单调性断裂counter reset如目标重启导致的计数回零会被自动校正且结果通常被“外推extrapolate”以覆盖区间向量选择器指定的完整时间范围——因此即使样本都是整数结果也可能不是整数。rate(v range-vector)计算区间向量内每条时间序列每秒的平均增长率并把结果外推到时间范围两端从而容忍漏抓取或抓取周期与时间范围不完全对齐。rate(http_requests_total{jobapi-server}[5m])rate只应用于计数器counter最适合用于告警和绘制变化缓慢的计数器曲线。对于本机直方图rate会构造一个新直方图其中每个分量sum、count、各 bucket都是区间内首个与末个本机直方图对应分量间的增长率但若某序列在区间内同时混有浮点与直方图样本则结果会被整体丢弃并附带 warn 级注解。关键使用守则将rate()与聚合操作符如sum()或任意以_over_time结尾的函数组合时必须先rate()后聚合。否则在目标重启时rate()无法识别计数器重置会得到错误的平均结果。这一守则同样适用于irate()。irate(v range-vector)基于区间向量中最后两个数据点计算每秒瞬时增长率同样自动校正计数器重置。两个样本必须同为浮点或同为直方图若最后两个样本一浮点一直方图则丢弃该序列并加 warn 注解。irate只应用于计数器。irate(http_requests_total{jobapi-server}[5m])irate适合绘制快速波动的计数器它对最新抖动非常敏感。而告警规则与慢变计数器应使用rate因为瞬时抖动可能重置FOR子句且全是零星尖峰的图难以阅读。increase(v range-vector)计算区间内时间序列的增量自动处理计数器重置并外推到完整时间范围increase(http_requests_total{jobapi-server}[5m])对直方图样本的处理方式与rate对称逐分量做增量混有浮点与直方图样本的序列被丢弃并加 warn 注解。文档特别强调increase是rate(v)乘以时间窗口秒数的语法糖主要用于人类可读性在 recording rule 中应使用rate这样增量能被一致地按每秒粒度跟踪。increase只应用于计数器。delta(v range-vector)计算区间向量内每条序列首值与末值之差并外推到完整时间范围——即使样本值全为整数也可能得到非整数结果。例如 CPU 温度两小时温差delta(cpu_temp_celsius{hostzeus}[2h])delta对直方图样本按“末直方图分量减首直方图分量”构造新直方图混有浮点与直方图样本的序列被丢弃并加 warn 注解。delta应只用于 gauge浮点与直方图皆可。idelta(v range-vector)计算区间向量中最后两个样本之差。两个样本必须同为浮点或同为直方图否则丢弃该序列并加 warn 注解。只用于 gauge。idelta与delta的关系正如同irate与rate的关系。deriv(v range-vector)用简单线性回归计算每条浮点时间序列在区间内的每秒导数。区间内必须至少有两个浮点样本若区间内出现Inf/-Inf计算出的斜率与偏移为NaN。只用于 gauge、只处理浮点样本只含直方图的序列被完全忽略浮点与直方图混合的序列只取浮点部分作为输入并附加 info 级注解说明。predict_linear(v range-vector, t scalar)基于区间向量v用简单线性回归预测当前时刻之后t秒时的取值。需要至少两个浮点样本区间内出现±Inf时预测值为NaN。典型用途是预测磁盘何时写满predict_linear(node_filesystem_free_bytes{mountpoint/}[1h], 24*3600) 0对直方图样本的处理规则与deriv相同仅浮点info 注解。changes(v range-vector)对每条输入序列返回其在时间范围内值发生变化的次数。浮点样本与直方图样本之间的切换也算一次变化而一个 counter 直方图样本换成值完全相同的 gauge 直方图样本或反向不算变化。resets(v range-vector)对每条输入序列返回时间范围内发生的计数器重置次数。两个连续浮点样本间任何数值下降都被视为一次重置。本机直方图的重置检测更复杂任意 bucket含零桶或观测计数的下降、此前有数据的 bucket 消失、零桶宽度减小以及任何不兼容的 schema分辨率下降式变更都被视为重置。resets只应用于计数器。浮点→直方图样本切换计为一次重置counter 直方图→gauge 直方图或反向也计为一次重置。double_exponential_smoothing(v range-vector, sf scalar, tf scalar)实验性对区间内每条浮点序列产生平滑值。平滑因子sf越低越重视旧数据趋势因子tf越高越重视数据中的趋势两者都必须在 0 与 1 之间。该算法也被称为 “Holt Linear” 双指数平滑可参考 NIST 工程统计手册中的双指数平滑章节。在 Prometheus V2 中它曾叫holt_winters因 Holt-Winters 通常指三指数平滑而造成混淆故更名。只用于 gauge、只处理浮点样本对直方图的处理与deriv相同。在 promql/functions.go 中其核心为funcDoubleExponentialSmoothing配合calcTrendValue等辅助函数。速率/增量族函数在源码里共享一套外推与计数器重置校正逻辑主要包括extrapolatedRate浮点外推、extendedRate/extendedHistogramRate、histogramRate直方图速率以及correctForCounterResets/correctForCounterResetsHistogram等见 promql/functions.go。直方图分析函数本机直方图native histogram的出现让直方图运算不再依赖一组_bucket序列。histogram_*系列函数在语义上同时覆盖 classic经典基于le上界的_bucket系列与本机直方图。histogram_count()、histogram_sum()与histogram_avg()histogram_count(v instant-vector)返回每个本机直方图样本中的观测计数histogram_sum(v instant-vector)返回观测值之和histogram_avg(v instant-vector)返回观测值的算术平均值。三者都忽略浮点样本即浮点样本不会出现在返回向量中。求一段窗口内的平均请求时延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(rate(http_request_duration_seconds[10m]))histogram_quantile(φ scalar, b instant-vector)计算 φ 分位数0 ≤ φ ≤ 1是使用最广泛的直方图函数。经典直方图输入b中的每个浮点样本被视作一个 bucket 的观测计数且必须携带le标签带le上界的标签值其余标签与指标名用于把 bucket 归并到各直方图不带le的浮点样本被静默忽略。经典 histogram 指标会自动产生_bucket后缀的系列。本机直方图输入b中的每个直方图样本被单独视为一个直方图来求分位数。在无命名冲突的前提下b可以混合经典与本机直方图。典型用例——过去 10 分钟请求时延的 P90。若指标是经典直方图bucket 系列名为http_request_duration_seconds_buckethistogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))若是本机直方图histogram_quantile(0.9, rate(http_request_duration_seconds[10m]))histogram_quantile会为http_request_duration_seconds的每种标签组合各算一个分位数要做跨标签聚合用sum()包住rate()。经典直方图因必须保留le需在by中显式列出按 job 聚合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])))聚合全部序列classic 只写lenative 无需byhistogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m]))) histogram_quantile(0.9, sum(rate(http_request_duration_seconds[10m])))分位数插值规则当 φ 值未恰落在某个 bucket 边界时函数会在 φ 落入的那个 bucket 内插值。经典直方图、自定义 bucket 边界的本机直方图以及本机直方图的零桶默认桶内观测值均匀分布线性插值标准指数分桶的本机直方图非零桶则假定样本在“更高分辨率的假设直方图”中均匀填充各子桶即指数插值。输入与返回值特例b的观测数为 0 时返回NaNφ 0 返回-Infφ 1 返回Infφ NaN返回NaN。经典直方图特例bucket 少于两个时返回NaN最高 bucket 的上界必须是Inf否则返回NaN若 φ 落在最高 bucket 内返回次高bucket 的上界最低 bucket 的上界大于 0 时假定其下界为 0并在其内部做线性插值否则 φ 落在最低 bucket 内时直接返回该 bucket 的上界。本机直方图特例标准指数分桶含NaN观测且 φ 落在某个已有桶内时由于NaN按Inf处理结果会向高值偏移info 注解提示标准指数分桶含NaN观测且 φ 高于所有已有桶时返回NaNinfo 注解有限宽度的零桶若直方图只在正桶有观测而无负桶观测则假定零桶不含负观测反之亦然。实用技巧histogram_quantile(0, v)可得到直方图内观测值的估计最小值histogram_quantile(1, v)得到估计最大值。对单调性破损的容错经典直方图桶是累积的正常应满足桶计数单调不减、相邻桶间无观测则计数相等。浮点精度例如sum(rate(...))带来的微小误差或非法数据可能破坏该假设。histogram_quantile会忽略相对差异小于两桶之和的万亿分之一1e-12的微小差异若即便如此仍存在非单调计数则把后续桶强制提升到前一桶的值以恢复单调此时会打出input to histogram_quantile needed to be fixed for monotonicity的 info 注解——遇到该注解意味着输入数据确有异常应定位并移除非法数据来源。histogram_quantiles()实验性histogram_quantiles(v instant-vector, quantile_label string, φ_1 scalar, φ_2 scalar, ...)可一次性计算 1 到 10 个 φ 分位数。分位数算法与histogram_quantile一致第二个参数字符串指定用于在结果中区分各分位数的标签名histogram_quantiles(sum(rate(foo[1m])), quantile, 0.9, 0.99) # {quantile0.9} 123 {quantile0.99} 128histogram_fraction(lower scalar, upper scalar, b instant-vector)估算观测值落在[lower, upper]区间内的比例适用于经典与本机直方图。输入规则与histogram_quantile相同浮点样本视为经典直方图的各桶计数本机直方图样本各自独立作为一个直方图。当下、上界不恰好落在 bucket 边界上时估算使用与histogram_quantile相同的插值方法精度取决于底层直方图的分辨率及边界与桶边界的贴合程度。经典直方图的桶往往稀疏随意选择远离桶边界的上下界会带来较大误差需要精确比例时更稳妥的做法是直接对 bucket 系列做运算例如计算 Apdex 得分的经典做法。例如计算过去一小时耗时不超过 200ms 的 HTTP 请求比例histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))Inf与-Inf是合法边界。例如若直方图包含负观测虽然请求耗时通常不会那么要统计“所有 ≤ 0.2 的观测”下界应选-Inf而非0。边界的含/不含inclusive/exclusive只在边界恰好与桶边界对齐时有意义此时取决于直方图 schema 定义标准指数 schema 对正值普遍采用上界含、下界不含负值相反不对齐时函数使用插值估算含不含边界便无关紧要。标准指数分桶本机直方图还有一个特例NaN观测被视为不落在任何桶中因此histogram_fraction(-Inf, Inf, b)实际返回的是非NaN观测的比例可能小于 1。histogram_stddev()与histogram_stdvar()估计histogram_stddev(v instant-vector)估计每个本机直方图样本观测值的标准差histogram_stdvar估计方差。估计时假定桶内所有观测值等于“桶边界均值”零桶与自定义边界桶取算术平均通常的指数桶取几何平均。两者都忽略浮点样本。标签操作函数label_join(v instant-vector, dst_label string, separator string, src_label_1 string, ...)把若干源标签src_label_1、src_label_2……的值用separator连接后写入目标标签dst_label。源标签个数不限对浮点与直方图样本同等处理label_join(up{jobapi-server,src1a,src2b,src3c}, foo, ,, src1, src2, src3) # 返回的每条序列新增 fooa,b,clabel_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)用 正则表达式regex匹配源标签src_label的值匹配成功则把replacement展开后的结果写入目标标签dst_label捕获组用$1、$2引用命名捕获组用$name引用匹配失败则原样返回该序列。对浮点与直方图样本同等处理label_replace(up{jobapi-server,servicea:c}, foo, $1, service, (.*):.*) # 结果在 service 标签为 a:c 的序列上新增 fooa label_replace(up{jobapi-server,servicea:c}, foo, $name, service, (?Pname.*):(?Pversion.*)) # 命名捕获组写法效果同上缺失检测与告警辅助函数这三者通常用于“序列不存在”时的告警是运维告警规则中很常见的模式。absent(v instant-vector)若传入向量含任何元素浮点或直方图样本均可返回空向量若不含元素返回一个值为 1 的单元素向量。在指标与标签组合不再存在时非常有用absent(nonexistent{jobmyjob}) # {jobmyjob} absent(nonexistent{jobmyjob,instance~.*}) # {jobmyjob} absent(sum(nonexistent{jobmyjob})) # {}前两个例子里absent()会尝试从输入向量中“智能地”推导输出单元素向量的标签。absent_over_time(v range-vector)语义与absent相同但输入是区间向量——判断的是某个时间范围内序列是否从未存在适合“连续一段时间无数据”的告警absent_over_time(nonexistent{jobmyjob}[1h]) # {jobmyjob} absent_over_time(nonexistent{jobmyjob,instance~.*}[1h]) # {jobmyjob} absent_over_time(sum(nonexistent{jobmyjob})[1h:]) # {}前两个例子同样会智能推导标签。present_over_time则是它的补集形态见下文aggregation_over_time一节。_over_time系列区间内随时间聚合以_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 ≤ φ ≤ 1stddev_over_time(range-vector)区间内浮点样本的总体标准差stdvar_over_time(range-vector)区间内浮点样本的总体方差last_over_time(range-vector)区间内最近的样本first_over_time(range-vector)区间内最早的样本present_over_time(range-vector)区间内只要序列出现过即返回 1。启用--enable-featurepromql-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)区间内最后样本的时间戳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按与对应聚合操作符一致的语义处理直方图样本若区间内某序列同时含浮点与直方图样本则对应结果从输出中整体移除并附 warn 级注解其余函数按“忽略直方图”处理区间内只有直方图样本的序列被静默移除浮点与直方图混合的区间只处理浮点样本并附 info 级注解说明。first_over_time(m[1m])与m offset 1m语义不同前者选出 1 分钟区间内部的第一个样本后者选出偏移区间之外、lookback 区间内最近的样本。这在范围查询中配合first_over_time(m[step()])使用尤其有价值——能保证选中的样本确实落在当前 range step 之内。排序函数sort(v instant-vector)按浮点样本值升序返回元素sort_desc(v)为降序。两者静默忽略直方图样本。sort_by_label(v instant-vector, label string, ...)按给定标签值升序排列标签值相同则按完整标签集排序sort_by_label_desc为降序。sort_by_label采用自然排序顺序对浮点与直方图样本同等处理。以上排序函数只影响瞬时查询的结果顺序——范围查询的结果永远保持固定输出顺序。注意sort、sort_desc会忽略直方图样本而sort_by_label/sort_by_label_desc不要求样本必须是浮点因此后者适用于含直方图的向量。sort_by_label系列目前是实验性函数。三角函数与单位换算三角函数以弧度为单位对输入向量中的直方图样本一律忽略边界特例遵循 Go 标准库math包对应函数Acos/Acosh/Asin/Asinh/Atan/Atanh/Cos/Cosh/Sin/Sinh/Tan/Tanh的 IEEE-754 行为acos(v)反余弦、acosh(v)反双曲余弦、asin(v)反正弦、asinh(v)反双曲正弦、atan(v)反正切、atanh(v)反双曲正切cos(v)余弦、cosh(v)双曲余弦、sin(v)正弦、sinh(v)双曲正弦、tan(v)正切、tanh(v)双曲正切角度/弧度换算deg(v)把弧度转角度、rad(v)把角度转弧度、pi()返回 π。特殊与实验性函数max_of(a scalar, b scalar)与min_of(a scalar, b scalar)实验性分别返回两个标量中较大/较小者用于在标量表达式中内联取极值。info()实验性info是改善info metric携带元数据的指标如target_info标签使用体验的实验性函数行为在未来版本中可能变化甚至被移除。info(v instant-vector, [data-label-selector instant-vector])为v中的每条序列查找“标识标签”匹配的 info 序列并把它们的“数据标签”非标识标签合并到结果序列上。info 序列的标识标签是唯一定位该序列的那部分标签当前实现默认假定为instance与job其余标签是数据标签。常规 Prometheus 视角下时间序列身份包含全部标签一旦数据标签变化info 函数视为旧序列结束、新序列开始而“逻辑视角”则是同一条 info 序列携带了不同的数据。传统做法是手写“join 查询”rate(http_server_request_duration_seconds_count[2m]) * on (job, instance) group_left (k8s_cluster_name) target_info这种写法冗长且脆弱若target_info的任何数据标签发生变化而旧序列未正确标记为 stale上面的查询最长会在 5 分钟lookback delta内因同时匹配新旧两个版本的target_info而失败。info函数既按“取较新序列”的方式解决冲突又因为知道可用的 info 序列及它们的标识标签而大幅简化语法info( rate(http_server_request_duration_seconds_count[2m]), {k8s_cluster_name~.} )省略第二参数即添加全部数据标签info(rate(http_server_request_duration_seconds_count[2m]))第二参数并非真正的瞬时向量它必须用花括号包起、且只允许包含标签匹配器作用是把要考虑的 info 序列和要添加到v的数据标签都限定住。若某时间戳上没有匹配的 info 序列例如 info 序列已过期行为取决于匹配器只要data-label-selector含任何不匹配空串的匹配器如{data~.}该序列就被丢弃必需的数据缺失若全部匹配器可匹配空串如{data~.*}或未提供选择器则原样返回未富集的序列。可用__name__匹配器限定 info 序列来源例如{__name__target_info}。当前限制默认只考虑名为target_info的 info 序列且假定标识标签恒为instance与job。可通过__name__匹配器扩展到其他名称例如{__name__~(target|build)_info}但标识标签仍必须是instance和job。仅提供取反的__name__匹配器如{__name__!target_info}时info会先考虑所有匹配._info的指标再应用取反过滤。若v中存在与选择器匹配的序列它们会被视为 info 序列原样返回。这些限制说明它目前仍是验证实用价值的实验最终版本将考虑所有匹配的 info 序列并采用各自正确的标识标签。实验性函数的启用与源码落点如何启用实验性函数上文标注“实验性”的函数start()、end()、step()、range()、double_exponential_smoothing()、histogram_quantiles()、max_of()、min_of()、info()、sort_by_label()、sort_by_label_desc()、mad_over_time()、ts_of_min_over_time()、ts_of_max_over_time()、ts_of_last_over_time()、ts_of_first_over_time()统一由特性开关控制。启动 Prometheus 服务时传入prometheus --enable-featurepromql-experimental-functions--enable-feature是逗号分隔的特性列表完整选项见 cmd/prometheus/main.go 中该 flag 的定义以及 特性开关文档其中的use-start-timestamps还是start_timestamp()生效的前提。相关特性类别在 util/features/features.go 中被登记如PromQLFunctions promql_functions解析时由 promql/parser/features.go 判断当函数带Experimental标记而解析器选项EnableExperimentalFunctions未开启时该函数不可用。全部函数在源码中的登记表PromQL 支持的每一个函数无论实验与否都登记在 promql/functions.go 的FunctionCalls映射中key 为函数名value 为对应的 Go 实现例如rate→funcRate、increase→funcIncrease、histogram_quantile→funcHistogramQuantile。从源码结构可以清晰地看到时间/上下文类函数time、timestamp、year等与日期族直接包装 Go 的time包取整/对数/三角函数通过simpleFloatFunc这类泛化辅助函数批量映射到标准库math函数速率类共享extrapolatedRate、extendedRate与直方图专用的histogramRate这正是文档反复强调“混用浮点与直方图样本会触发 warn/info 注解”的实现基础histogram_quantile的核心分位数/插值算法在 promql/quantile.go 中实现分线性与指数两种插值其中包含文档所述的 1e-12 单调性容差与强制单调化逻辑。文档中关于注解级别的约定warn结果被丢弃、数据不可信info仅提示未使用的样本类型在 promql/functions.go 各实现函数与 util/annotations 包中可以逐一对应promql/functions_test.go与promql/promqltest/目录下的大量测试用例则为上述边界语义提供了可执行的验证样本。附函数选用速查场景推荐函数输入类型样本类型计数器每秒平均速率告警rate()range-vectorcounter计数器每秒瞬时速率绘图irate()range-vectorcounter区间内总增量increase()range-vectorcountergauge 首末值差delta()/idelta()range-vectorgaugegauge 变化趋势预测deriv()/predict_linear()range-vectorgauge区间内重取样首/末/计数/分位数/方差…*_over_timerange-vector通用经典/本机直方图分位数histogram_quantile()instant-vectorhistogram直方图占比估算histogram_fraction()instant-vectorhistogram直方图均值/和/计数histogram_avg/sum/count()instant-vectorhistogram无数据告警absent()/absent_over_time()视函数而定—标签拼接/改写label_join()/label_replace()instant-vector通用序列排序sort/sort_by_label系列instant-vector通用最后再次强调两组贯穿全篇的使用纪律速率/增量类函数只用于语义匹配的度量类型counter 或 gauge错误混用会得出无意义结果任何时间聚合或跨序列聚合都应放在rate()/irate()之后执行否则计数器重置将无法被正确识别。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prometheus PromQL 查询函数完全参考：签名、语义与源码实现
Prometheus PromQL 查询函数完全参考签名、语义与源码实现【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheusPromQLPrometheus Query Language内置了大量查询函数覆盖数学运算、计数器速率、直方图分析、时间日期、标签改写等场景是编写告警规则与仪表盘表达式的核心工具。本文以仓库内的 PromQL 函数官方文档 为骨架逐组讲解每个函数的签名、语义、边界情况与经典用例并结合 promql/functions.go 等源码说明底层实现与注解行为。读完本文你将能够准确选用函数、理解函数对浮点样本与本机直方图样本的不同处理方式并掌握实验性函数的启用方法。阅读前必须理解的三条通用约定在使用任何 PromQL 函数前需要先建立三个全局观念它们贯穿下面所有函数的行为描述。默认参数部分函数带有默认实参例如year(vvector(time()) instant-vector)含义是函数有一个 instant-vector瞬时向量类型的参数v当调用时未显式提供时它自动默认取表达式vector(time())的求值结果。同类的时间/日期函数如hour()、month()都遵循这一约定。瞬时向量与区间向量参数类型标注为instant-vector的函数通常作用在某一刻的一组样本上标注为range-vector区间向量通常写作metric[5m]的函数则作用在时间窗口内的全部样本上用于计算速率、增量或随时间聚合。浮点样本与本机直方图样本Prometheus 时间序列可以同时承载 float浮点样本和 native histogram本机直方图样本。绝大多数函数对浮点样本运算时会静默忽略直方图样本而速率/增量类函数与histogram_*系列则专门针对直方图语义做了定义。个别函数对“区间内同时出现浮点与直方图样本”的情况会丢弃对应序列并以 warn/info 级注解annotation提示——这一点是理解许多“奇怪行为”的关键在文末的源码剖析中会展开。有关聚合操作符、正则表达式匹配等基础语法可参考 聚合操作符 与 正则表达式。数学与取整函数abs(v instant-vector)返回输入向量中所有浮点样本的绝对值。直方图样本被静默忽略。ceil(v instant-vector)与floor(v instant-vector)ceil向上取整到不小于原值的最小整数floor向下取整到不大于原值的最大整数。两者都静默忽略直方图样本并遵循 IEEE-754 特例ceil(Inf) Inf、ceil(±0) ±0、ceil(1.49) 2.0、ceil(1.78) 2.0floor(Inf) Inf、floor(±0) ±0、floor(1.49) 1.0、floor(1.78) 1.0round(v instant-vector, to_nearest1 scalar)把所有样本值四舍五入到最近的整数平局恰好在中间时向上取整。可选参数to_nearest指定取整的“步长”即样本值需要舍入到的最近倍数该倍数也可以是小数例如round(http_requests_total / 1000, 10) # 以 10 为单位取整直方图样本被静默忽略。clamp()、clamp_max()与clamp_min()clamp(v instant-vector, min scalar, max scalar)把样本值限制在[min, max]区间内。clamp_max(v instant-vector, max scalar)只设置上限。clamp_min(v instant-vector, min scalar)只设置下限。三者的边界特例如下clamp若min max返回空向量若min或max为NaN返回NaN若min为-Inf且max为Inf浮点样本原样保留。clamp_maxmax为NaN时返回NaNmax为Inf时样本不变max为-Inf时所有浮点样本都被设为-Inf。clamp_minmin为NaN时返回NaNmin为-Inf时样本不变min为Inf时所有浮点样本都被设为Inf。三个函数都静默忽略直方图样本。在源码 promql/functions.go 中它们统一由clamp(vec, minVal, maxVal, enh)辅助函数及funcClamp/funcClampMax/funcClampMin三个入口实现。对数与指数exp(v instant-vector)对每个浮点样本计算自然指数。特例Exp(Inf) Inf、Exp(NaN) NaN。ln(v instant-vector)自然对数。特例ln(Inf) Inf、ln(0) -Inf、ln(x0) NaN、ln(NaN) NaN。log2(v instant-vector)以 2 为底的对数特例与ln一致。log10(v instant-vector)以 10 为底的对数特例与ln一致。sqrt(v instant-vector)平方根。以上函数均静默忽略直方图样本。sgn(v instant-vector)返回样本值的符号值为正返回1为负返回-1等于零返回0。直方图样本被静默忽略。scalar(v instant-vector)与vector(s scalar)scalar若输入向量恰好只有一个含浮点样本的元素返回该样本值作为标量否则返回NaN。直方图样本被静默忽略。vector将标量s包装成一个无标签的单元素瞬时向量。这一对函数常用于“标量与向量混用”的表达式拼接。时间与日期函数无参时钟类time()返回自 1970-01-01 UTC 以来的秒数。注意它返回的不是“当前真实时间”而是该表达式被求值的时间点即查询评估时间。在源码中它由 promql/functions.go 的funcTime实现。timestamp(v instant-vector)返回输入向量中每个样本自身的时间戳自 Unix epoch 起的秒数对浮点与直方图样本一视同仁。start_timestamp(v instant-vector)返回给定向量每个样本的起始时间戳。注意它只作用于直接传入的瞬时向量且必须开启--enable-featureuse-start-timestamps若作用于普通表达式或未开启该特性则返回空结果。日期分解类UTC均默认参数vvector(time())这一组函数把样本值当作时间戳自 1970-01-01 UTC 的秒数在 UTC 时区内分解并返回对应字段函数返回值范围含义year(vvector(time()))年份返回给定时间的年份month(vvector(time()))1–12月份1 表示一月day_of_month(vvector(time()))1–31当月第几日day_of_week(vvector(time()))0–6星期几0 表示周日day_of_year(vvector(time()))1–365闰年 366当年第几日days_in_month(vvector(time()))28–31当月天数hour(vvector(time()))0–23当日第几小时minute(vvector(time()))0–59小时内第几分钟它们全部静默忽略直方图样本。由于这类函数的结果依赖求值时间days_in_month、day_of_month、day_of_week、day_of_year、hour、minute、month、year、time、predict_linear等都被列入源码中的AtModifierUnsafeFunctionspromql/functions.go意味着它们与修饰符组合时可能不安全。查询上下文类实验性以下函数把“当前查询上下文”暴露为标量秒数必须在启用promql-experimental-functions特性后可用start()返回当前 range query范围查询评估的起始时间戳对瞬时查询等价于评估时间戳。end()返回当前 range query 评估的结束时间戳对瞬时查询等价于评估时间戳。step()返回当前查询的分辨率步长秒数对瞬时查询返回0。range()返回当前 range query 的时间跨度秒数等价于end() - start()对瞬时查询返回0。从源码看这四者在FunctionCalls注册表中的实现均为nil注释标明它们会被foldQueryContextFunctions折叠为 NumberLiteralpromql/functions.go也就是说它们在语法分析/常量折叠阶段就被转换成具体数字而非运行时求值。计数器、速率与增量函数这一组是 PromQL 最核心的函数族全部要求range-vector输入。理解它们的公共点很重要单调性断裂counter reset如目标重启导致的计数回零会被自动校正且结果通常被“外推extrapolate”以覆盖区间向量选择器指定的完整时间范围——因此即使样本都是整数结果也可能不是整数。rate(v range-vector)计算区间向量内每条时间序列每秒的平均增长率并把结果外推到时间范围两端从而容忍漏抓取或抓取周期与时间范围不完全对齐。rate(http_requests_total{jobapi-server}[5m])rate只应用于计数器counter最适合用于告警和绘制变化缓慢的计数器曲线。对于本机直方图rate会构造一个新直方图其中每个分量sum、count、各 bucket都是区间内首个与末个本机直方图对应分量间的增长率但若某序列在区间内同时混有浮点与直方图样本则结果会被整体丢弃并附带 warn 级注解。关键使用守则将rate()与聚合操作符如sum()或任意以_over_time结尾的函数组合时必须先rate()后聚合。否则在目标重启时rate()无法识别计数器重置会得到错误的平均结果。这一守则同样适用于irate()。irate(v range-vector)基于区间向量中最后两个数据点计算每秒瞬时增长率同样自动校正计数器重置。两个样本必须同为浮点或同为直方图若最后两个样本一浮点一直方图则丢弃该序列并加 warn 注解。irate只应用于计数器。irate(http_requests_total{jobapi-server}[5m])irate适合绘制快速波动的计数器它对最新抖动非常敏感。而告警规则与慢变计数器应使用rate因为瞬时抖动可能重置FOR子句且全是零星尖峰的图难以阅读。increase(v range-vector)计算区间内时间序列的增量自动处理计数器重置并外推到完整时间范围increase(http_requests_total{jobapi-server}[5m])对直方图样本的处理方式与rate对称逐分量做增量混有浮点与直方图样本的序列被丢弃并加 warn 注解。文档特别强调increase是rate(v)乘以时间窗口秒数的语法糖主要用于人类可读性在 recording rule 中应使用rate这样增量能被一致地按每秒粒度跟踪。increase只应用于计数器。delta(v range-vector)计算区间向量内每条序列首值与末值之差并外推到完整时间范围——即使样本值全为整数也可能得到非整数结果。例如 CPU 温度两小时温差delta(cpu_temp_celsius{hostzeus}[2h])delta对直方图样本按“末直方图分量减首直方图分量”构造新直方图混有浮点与直方图样本的序列被丢弃并加 warn 注解。delta应只用于 gauge浮点与直方图皆可。idelta(v range-vector)计算区间向量中最后两个样本之差。两个样本必须同为浮点或同为直方图否则丢弃该序列并加 warn 注解。只用于 gauge。idelta与delta的关系正如同irate与rate的关系。deriv(v range-vector)用简单线性回归计算每条浮点时间序列在区间内的每秒导数。区间内必须至少有两个浮点样本若区间内出现Inf/-Inf计算出的斜率与偏移为NaN。只用于 gauge、只处理浮点样本只含直方图的序列被完全忽略浮点与直方图混合的序列只取浮点部分作为输入并附加 info 级注解说明。predict_linear(v range-vector, t scalar)基于区间向量v用简单线性回归预测当前时刻之后t秒时的取值。需要至少两个浮点样本区间内出现±Inf时预测值为NaN。典型用途是预测磁盘何时写满predict_linear(node_filesystem_free_bytes{mountpoint/}[1h], 24*3600) 0对直方图样本的处理规则与deriv相同仅浮点info 注解。changes(v range-vector)对每条输入序列返回其在时间范围内值发生变化的次数。浮点样本与直方图样本之间的切换也算一次变化而一个 counter 直方图样本换成值完全相同的 gauge 直方图样本或反向不算变化。resets(v range-vector)对每条输入序列返回时间范围内发生的计数器重置次数。两个连续浮点样本间任何数值下降都被视为一次重置。本机直方图的重置检测更复杂任意 bucket含零桶或观测计数的下降、此前有数据的 bucket 消失、零桶宽度减小以及任何不兼容的 schema分辨率下降式变更都被视为重置。resets只应用于计数器。浮点→直方图样本切换计为一次重置counter 直方图→gauge 直方图或反向也计为一次重置。double_exponential_smoothing(v range-vector, sf scalar, tf scalar)实验性对区间内每条浮点序列产生平滑值。平滑因子sf越低越重视旧数据趋势因子tf越高越重视数据中的趋势两者都必须在 0 与 1 之间。该算法也被称为 “Holt Linear” 双指数平滑可参考 NIST 工程统计手册中的双指数平滑章节。在 Prometheus V2 中它曾叫holt_winters因 Holt-Winters 通常指三指数平滑而造成混淆故更名。只用于 gauge、只处理浮点样本对直方图的处理与deriv相同。在 promql/functions.go 中其核心为funcDoubleExponentialSmoothing配合calcTrendValue等辅助函数。速率/增量族函数在源码里共享一套外推与计数器重置校正逻辑主要包括extrapolatedRate浮点外推、extendedRate/extendedHistogramRate、histogramRate直方图速率以及correctForCounterResets/correctForCounterResetsHistogram等见 promql/functions.go。直方图分析函数本机直方图native histogram的出现让直方图运算不再依赖一组_bucket序列。histogram_*系列函数在语义上同时覆盖 classic经典基于le上界的_bucket系列与本机直方图。histogram_count()、histogram_sum()与histogram_avg()histogram_count(v instant-vector)返回每个本机直方图样本中的观测计数histogram_sum(v instant-vector)返回观测值之和histogram_avg(v instant-vector)返回观测值的算术平均值。三者都忽略浮点样本即浮点样本不会出现在返回向量中。求一段窗口内的平均请求时延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(rate(http_request_duration_seconds[10m]))histogram_quantile(φ scalar, b instant-vector)计算 φ 分位数0 ≤ φ ≤ 1是使用最广泛的直方图函数。经典直方图输入b中的每个浮点样本被视作一个 bucket 的观测计数且必须携带le标签带le上界的标签值其余标签与指标名用于把 bucket 归并到各直方图不带le的浮点样本被静默忽略。经典 histogram 指标会自动产生_bucket后缀的系列。本机直方图输入b中的每个直方图样本被单独视为一个直方图来求分位数。在无命名冲突的前提下b可以混合经典与本机直方图。典型用例——过去 10 分钟请求时延的 P90。若指标是经典直方图bucket 系列名为http_request_duration_seconds_buckethistogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))若是本机直方图histogram_quantile(0.9, rate(http_request_duration_seconds[10m]))histogram_quantile会为http_request_duration_seconds的每种标签组合各算一个分位数要做跨标签聚合用sum()包住rate()。经典直方图因必须保留le需在by中显式列出按 job 聚合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])))聚合全部序列classic 只写lenative 无需byhistogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m]))) histogram_quantile(0.9, sum(rate(http_request_duration_seconds[10m])))分位数插值规则当 φ 值未恰落在某个 bucket 边界时函数会在 φ 落入的那个 bucket 内插值。经典直方图、自定义 bucket 边界的本机直方图以及本机直方图的零桶默认桶内观测值均匀分布线性插值标准指数分桶的本机直方图非零桶则假定样本在“更高分辨率的假设直方图”中均匀填充各子桶即指数插值。输入与返回值特例b的观测数为 0 时返回NaNφ 0 返回-Infφ 1 返回Infφ NaN返回NaN。经典直方图特例bucket 少于两个时返回NaN最高 bucket 的上界必须是Inf否则返回NaN若 φ 落在最高 bucket 内返回次高bucket 的上界最低 bucket 的上界大于 0 时假定其下界为 0并在其内部做线性插值否则 φ 落在最低 bucket 内时直接返回该 bucket 的上界。本机直方图特例标准指数分桶含NaN观测且 φ 落在某个已有桶内时由于NaN按Inf处理结果会向高值偏移info 注解提示标准指数分桶含NaN观测且 φ 高于所有已有桶时返回NaNinfo 注解有限宽度的零桶若直方图只在正桶有观测而无负桶观测则假定零桶不含负观测反之亦然。实用技巧histogram_quantile(0, v)可得到直方图内观测值的估计最小值histogram_quantile(1, v)得到估计最大值。对单调性破损的容错经典直方图桶是累积的正常应满足桶计数单调不减、相邻桶间无观测则计数相等。浮点精度例如sum(rate(...))带来的微小误差或非法数据可能破坏该假设。histogram_quantile会忽略相对差异小于两桶之和的万亿分之一1e-12的微小差异若即便如此仍存在非单调计数则把后续桶强制提升到前一桶的值以恢复单调此时会打出input to histogram_quantile needed to be fixed for monotonicity的 info 注解——遇到该注解意味着输入数据确有异常应定位并移除非法数据来源。histogram_quantiles()实验性histogram_quantiles(v instant-vector, quantile_label string, φ_1 scalar, φ_2 scalar, ...)可一次性计算 1 到 10 个 φ 分位数。分位数算法与histogram_quantile一致第二个参数字符串指定用于在结果中区分各分位数的标签名histogram_quantiles(sum(rate(foo[1m])), quantile, 0.9, 0.99) # {quantile0.9} 123 {quantile0.99} 128histogram_fraction(lower scalar, upper scalar, b instant-vector)估算观测值落在[lower, upper]区间内的比例适用于经典与本机直方图。输入规则与histogram_quantile相同浮点样本视为经典直方图的各桶计数本机直方图样本各自独立作为一个直方图。当下、上界不恰好落在 bucket 边界上时估算使用与histogram_quantile相同的插值方法精度取决于底层直方图的分辨率及边界与桶边界的贴合程度。经典直方图的桶往往稀疏随意选择远离桶边界的上下界会带来较大误差需要精确比例时更稳妥的做法是直接对 bucket 系列做运算例如计算 Apdex 得分的经典做法。例如计算过去一小时耗时不超过 200ms 的 HTTP 请求比例histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))Inf与-Inf是合法边界。例如若直方图包含负观测虽然请求耗时通常不会那么要统计“所有 ≤ 0.2 的观测”下界应选-Inf而非0。边界的含/不含inclusive/exclusive只在边界恰好与桶边界对齐时有意义此时取决于直方图 schema 定义标准指数 schema 对正值普遍采用上界含、下界不含负值相反不对齐时函数使用插值估算含不含边界便无关紧要。标准指数分桶本机直方图还有一个特例NaN观测被视为不落在任何桶中因此histogram_fraction(-Inf, Inf, b)实际返回的是非NaN观测的比例可能小于 1。histogram_stddev()与histogram_stdvar()估计histogram_stddev(v instant-vector)估计每个本机直方图样本观测值的标准差histogram_stdvar估计方差。估计时假定桶内所有观测值等于“桶边界均值”零桶与自定义边界桶取算术平均通常的指数桶取几何平均。两者都忽略浮点样本。标签操作函数label_join(v instant-vector, dst_label string, separator string, src_label_1 string, ...)把若干源标签src_label_1、src_label_2……的值用separator连接后写入目标标签dst_label。源标签个数不限对浮点与直方图样本同等处理label_join(up{jobapi-server,src1a,src2b,src3c}, foo, ,, src1, src2, src3) # 返回的每条序列新增 fooa,b,clabel_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)用 正则表达式regex匹配源标签src_label的值匹配成功则把replacement展开后的结果写入目标标签dst_label捕获组用$1、$2引用命名捕获组用$name引用匹配失败则原样返回该序列。对浮点与直方图样本同等处理label_replace(up{jobapi-server,servicea:c}, foo, $1, service, (.*):.*) # 结果在 service 标签为 a:c 的序列上新增 fooa label_replace(up{jobapi-server,servicea:c}, foo, $name, service, (?Pname.*):(?Pversion.*)) # 命名捕获组写法效果同上缺失检测与告警辅助函数这三者通常用于“序列不存在”时的告警是运维告警规则中很常见的模式。absent(v instant-vector)若传入向量含任何元素浮点或直方图样本均可返回空向量若不含元素返回一个值为 1 的单元素向量。在指标与标签组合不再存在时非常有用absent(nonexistent{jobmyjob}) # {jobmyjob} absent(nonexistent{jobmyjob,instance~.*}) # {jobmyjob} absent(sum(nonexistent{jobmyjob})) # {}前两个例子里absent()会尝试从输入向量中“智能地”推导输出单元素向量的标签。absent_over_time(v range-vector)语义与absent相同但输入是区间向量——判断的是某个时间范围内序列是否从未存在适合“连续一段时间无数据”的告警absent_over_time(nonexistent{jobmyjob}[1h]) # {jobmyjob} absent_over_time(nonexistent{jobmyjob,instance~.*}[1h]) # {jobmyjob} absent_over_time(sum(nonexistent{jobmyjob})[1h:]) # {}前两个例子同样会智能推导标签。present_over_time则是它的补集形态见下文aggregation_over_time一节。_over_time系列区间内随时间聚合以_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 ≤ φ ≤ 1stddev_over_time(range-vector)区间内浮点样本的总体标准差stdvar_over_time(range-vector)区间内浮点样本的总体方差last_over_time(range-vector)区间内最近的样本first_over_time(range-vector)区间内最早的样本present_over_time(range-vector)区间内只要序列出现过即返回 1。启用--enable-featurepromql-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)区间内最后样本的时间戳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按与对应聚合操作符一致的语义处理直方图样本若区间内某序列同时含浮点与直方图样本则对应结果从输出中整体移除并附 warn 级注解其余函数按“忽略直方图”处理区间内只有直方图样本的序列被静默移除浮点与直方图混合的区间只处理浮点样本并附 info 级注解说明。first_over_time(m[1m])与m offset 1m语义不同前者选出 1 分钟区间内部的第一个样本后者选出偏移区间之外、lookback 区间内最近的样本。这在范围查询中配合first_over_time(m[step()])使用尤其有价值——能保证选中的样本确实落在当前 range step 之内。排序函数sort(v instant-vector)按浮点样本值升序返回元素sort_desc(v)为降序。两者静默忽略直方图样本。sort_by_label(v instant-vector, label string, ...)按给定标签值升序排列标签值相同则按完整标签集排序sort_by_label_desc为降序。sort_by_label采用自然排序顺序对浮点与直方图样本同等处理。以上排序函数只影响瞬时查询的结果顺序——范围查询的结果永远保持固定输出顺序。注意sort、sort_desc会忽略直方图样本而sort_by_label/sort_by_label_desc不要求样本必须是浮点因此后者适用于含直方图的向量。sort_by_label系列目前是实验性函数。三角函数与单位换算三角函数以弧度为单位对输入向量中的直方图样本一律忽略边界特例遵循 Go 标准库math包对应函数Acos/Acosh/Asin/Asinh/Atan/Atanh/Cos/Cosh/Sin/Sinh/Tan/Tanh的 IEEE-754 行为acos(v)反余弦、acosh(v)反双曲余弦、asin(v)反正弦、asinh(v)反双曲正弦、atan(v)反正切、atanh(v)反双曲正切cos(v)余弦、cosh(v)双曲余弦、sin(v)正弦、sinh(v)双曲正弦、tan(v)正切、tanh(v)双曲正切角度/弧度换算deg(v)把弧度转角度、rad(v)把角度转弧度、pi()返回 π。特殊与实验性函数max_of(a scalar, b scalar)与min_of(a scalar, b scalar)实验性分别返回两个标量中较大/较小者用于在标量表达式中内联取极值。info()实验性info是改善info metric携带元数据的指标如target_info标签使用体验的实验性函数行为在未来版本中可能变化甚至被移除。info(v instant-vector, [data-label-selector instant-vector])为v中的每条序列查找“标识标签”匹配的 info 序列并把它们的“数据标签”非标识标签合并到结果序列上。info 序列的标识标签是唯一定位该序列的那部分标签当前实现默认假定为instance与job其余标签是数据标签。常规 Prometheus 视角下时间序列身份包含全部标签一旦数据标签变化info 函数视为旧序列结束、新序列开始而“逻辑视角”则是同一条 info 序列携带了不同的数据。传统做法是手写“join 查询”rate(http_server_request_duration_seconds_count[2m]) * on (job, instance) group_left (k8s_cluster_name) target_info这种写法冗长且脆弱若target_info的任何数据标签发生变化而旧序列未正确标记为 stale上面的查询最长会在 5 分钟lookback delta内因同时匹配新旧两个版本的target_info而失败。info函数既按“取较新序列”的方式解决冲突又因为知道可用的 info 序列及它们的标识标签而大幅简化语法info( rate(http_server_request_duration_seconds_count[2m]), {k8s_cluster_name~.} )省略第二参数即添加全部数据标签info(rate(http_server_request_duration_seconds_count[2m]))第二参数并非真正的瞬时向量它必须用花括号包起、且只允许包含标签匹配器作用是把要考虑的 info 序列和要添加到v的数据标签都限定住。若某时间戳上没有匹配的 info 序列例如 info 序列已过期行为取决于匹配器只要data-label-selector含任何不匹配空串的匹配器如{data~.}该序列就被丢弃必需的数据缺失若全部匹配器可匹配空串如{data~.*}或未提供选择器则原样返回未富集的序列。可用__name__匹配器限定 info 序列来源例如{__name__target_info}。当前限制默认只考虑名为target_info的 info 序列且假定标识标签恒为instance与job。可通过__name__匹配器扩展到其他名称例如{__name__~(target|build)_info}但标识标签仍必须是instance和job。仅提供取反的__name__匹配器如{__name__!target_info}时info会先考虑所有匹配._info的指标再应用取反过滤。若v中存在与选择器匹配的序列它们会被视为 info 序列原样返回。这些限制说明它目前仍是验证实用价值的实验最终版本将考虑所有匹配的 info 序列并采用各自正确的标识标签。实验性函数的启用与源码落点如何启用实验性函数上文标注“实验性”的函数start()、end()、step()、range()、double_exponential_smoothing()、histogram_quantiles()、max_of()、min_of()、info()、sort_by_label()、sort_by_label_desc()、mad_over_time()、ts_of_min_over_time()、ts_of_max_over_time()、ts_of_last_over_time()、ts_of_first_over_time()统一由特性开关控制。启动 Prometheus 服务时传入prometheus --enable-featurepromql-experimental-functions--enable-feature是逗号分隔的特性列表完整选项见 cmd/prometheus/main.go 中该 flag 的定义以及 特性开关文档其中的use-start-timestamps还是start_timestamp()生效的前提。相关特性类别在 util/features/features.go 中被登记如PromQLFunctions promql_functions解析时由 promql/parser/features.go 判断当函数带Experimental标记而解析器选项EnableExperimentalFunctions未开启时该函数不可用。全部函数在源码中的登记表PromQL 支持的每一个函数无论实验与否都登记在 promql/functions.go 的FunctionCalls映射中key 为函数名value 为对应的 Go 实现例如rate→funcRate、increase→funcIncrease、histogram_quantile→funcHistogramQuantile。从源码结构可以清晰地看到时间/上下文类函数time、timestamp、year等与日期族直接包装 Go 的time包取整/对数/三角函数通过simpleFloatFunc这类泛化辅助函数批量映射到标准库math函数速率类共享extrapolatedRate、extendedRate与直方图专用的histogramRate这正是文档反复强调“混用浮点与直方图样本会触发 warn/info 注解”的实现基础histogram_quantile的核心分位数/插值算法在 promql/quantile.go 中实现分线性与指数两种插值其中包含文档所述的 1e-12 单调性容差与强制单调化逻辑。文档中关于注解级别的约定warn结果被丢弃、数据不可信info仅提示未使用的样本类型在 promql/functions.go 各实现函数与 util/annotations 包中可以逐一对应promql/functions_test.go与promql/promqltest/目录下的大量测试用例则为上述边界语义提供了可执行的验证样本。附函数选用速查场景推荐函数输入类型样本类型计数器每秒平均速率告警rate()range-vectorcounter计数器每秒瞬时速率绘图irate()range-vectorcounter区间内总增量increase()range-vectorcountergauge 首末值差delta()/idelta()range-vectorgaugegauge 变化趋势预测deriv()/predict_linear()range-vectorgauge区间内重取样首/末/计数/分位数/方差…*_over_timerange-vector通用经典/本机直方图分位数histogram_quantile()instant-vectorhistogram直方图占比估算histogram_fraction()instant-vectorhistogram直方图均值/和/计数histogram_avg/sum/count()instant-vectorhistogram无数据告警absent()/absent_over_time()视函数而定—标签拼接/改写label_join()/label_replace()instant-vector通用序列排序sort/sort_by_label系列instant-vector通用最后再次强调两组贯穿全篇的使用纪律速率/增量类函数只用于语义匹配的度量类型counter 或 gauge错误混用会得出无意义结果任何时间聚合或跨序列聚合都应放在rate()/irate()之后执行否则计数器重置将无法被正确识别。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
