Prometheus 查询语言 PromQL | 鹏之背

date

related_level

slug

type

relate_date

summary

status

PromQL 数据模型

PromQL 在瞬时查询和范围查询中的语法一致，且所有查询均可通过 HTTP API 被外部程序调用

瞬时查询（Instant Query）：在单个时间点求值，结果以表格形式展示（UI 中的 "Table" 标签）

范围查询（Range Query）：在指定时间范围内按固定步长多次执行瞬时查询，结果用于绘图（UI 中的 "Graph" 标签）

PromQL 查询返回的样本有两种类型：Float, Histogram

Float：简单的浮点数值。

被用作 Counter（通常以 _total 结尾）或 Gauge，但样本本身不存储“类型信息”，需用户自行根据命名约定判断
对 Gauge 类型误用 rate() 等函数时，Prometheus 不会报错，即使结果可能无意义

Native Histogram：包含完整的直方图数据（buckets、count、sum）

明确区分 Counter Histogram 和 Gauge Histogram，并内置类型信息
若对 Gauge Histogram 错误使用 rate()，Prometheus 会返回结果并附带警告，提升查询安全性

PromQL 表达式求值支持返回四种数据类型

Scalar：单个浮点数值

Instant vector：一组时间序列，每个在同一时间点有一个样本（用于图表和告警）

Range vector：一组时间序列，每个包含一段时间内的多个样本（仅用于函数内部，不能作为最终查询结果）

String：字符串（目前未实际使用）

两种查询的数据类型限制

瞬时查询可返回任意类型

范围查询仅允许 Scalar 或 Instant vector 作为最终结果

PromQL 语法规范

PromQL 字面量（Literals） 包括字符串和数值（含时间间隔）

字符串字面量可用单引号 '、双引号 " 或反引号 ` 表示

单/双引号内支持转义（如 \n, \t, \xNN 等，规则同 Go）
反引号内不解析转义字符，且保留换行符（与 Go 不同）

浮点数字面量支持整数、小数、科学计数法、十六进制（0x...）、Inf、NaN

可用下划线 _ 分隔数字以提高可读性

如 1_000_000

时间间隔表示

使用整数 + 时间单位表示秒数，单位包括：

ms（毫秒）、s（秒）、m（分）、h（时）、d（天）、w（周）、y（年）

仅支持整数，不支持浮点

如 1.5h 无效

十六进制、Inf、NaN 不能加单位
多单位可组合，从大到小排列且不重复

如 1h30m、54s321ms

PromQL 使用选择器来指定要查询的时间序列数据

瞬时向量选择器（Instant Vector Selectors）选取每个时间序列在某一时刻的最新样本

基本语法

http_requests_total

选择器必须包含指标名或至少一个非空标签匹配器

非法：{job=～".*"}

等于全匹配

合法：{job=～".+"} 或 {job=～".*", method="GET"}

标签过滤 {}

匹配空值时（如 env=""）也会选中未设置该标签的时间序列

样例

http_requests_total{job="prometheus",group="canary"}

使用 __name__ 匹配指标名，避免与关键字冲突

关键字

bool, on, ignoring, group_left, group_right

样例

{__name__="http_requests_total"}
{__name__=～"job:.*"}
{__name__="on"} 而非 on{}

范围向量选择器（Range Vector Selectors）选取过去一段时间内的多个样本，用于函数（如 rate()）内部

时间窗口为左开右闭区间

基本语法：在瞬时选择器后加 [时间窗口]

http_requests_total{job="prometheus"}[5m]

PromQL 子查询 [] 允许针对给定的 range 和 resolution 运行即时查询，返回 Range vector

可以理解为：从特定时间点开始，向过去 range 时间范围内每隔 resolution 时间点执行一次 instant_query

基本语法

<instant_query> '[' <range> ':' [<resolution>] ']'[ @ <float_literal> ] [ offset <float_literal> ]
<resolution> 可选，为两个采样时间点之间的间隔，通常 ≈ step

样例

avg_over_time( rate(http_requests_total[1m])[10m:30s] )
过去 10 分钟内每 30 秒算一次 rate() 再对这些点求平均

1m 是瞬时向量 http_requests_total 的范围向量选择器时间窗口

对于每个 http_requests_total 取过去 1m 的数据点

10m 为子查询的时间窗口长度，回溯过去 10m
30s 为子查询生成样本点的步长，每 30 秒一次执行一次 rate()

PromQL 修饰符和运算符

参考资料

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

https://www.liwenzhou.com/posts/Go/prometheus-operators/

offset 修饰符将查询时间偏移到过去或未来

必须紧跟选择器

http_requests_total offset 5m
sum(http_requests_total{method="GET"} offset 5m)
sum(http_requests_total{method="GET"}) offset 5m

错误语法

支持范围向量

rate(http_requests_total[5m] offset 1w)

支持负偏移

rate(http_requests_total[5m] offset -1w)

@ 修饰符指定绝对 Unix 时间戳作为查询时间点

必须紧跟选择器

http_requests_total @1609746000
sum(http_requests_total{method="GET"} @ 1609746000)
sum(http_requests_total{method="GET"}) @ 1609746000

错误语法

支持范围向量

rate(http_requests_total[5m] @1609746000)

支持特殊值

@ start() → 范围查询的开始时间
@ end() → 范围查询的结束时间

可与 offset 组合，顺序无关

http_requests_total @ 1609746000 offset 5m
http_requests_total offset 5m @ 1609746000

bool 修饰符在比较二元运算中用来改变比较的结果形式

默认行为（不使用 bool）

条件为 true 的时间序列 → 保留
条件为 false 的时间序列 → 直接丢弃
没有匹配项 / 非法比较（如 histogram）→ 无结果

node_memory_Active_bytes > bool node_memory_MemFree_bytes

丢弃未匹配项

1024 >= 42

报错

加上 bool 后，比较运算不再过滤，而是返回数值结果，且丢弃指标名称

条件为 true → 值为 1

1024 >= bool 42 返回 1

条件为 false → 值为 0
仍然需要 向量匹配成功，否则无结果

标签匹配运算符 =, !=, =~, !~

操作符	含义
`=`	精确等于
`!=`	不等于
`=～`	正则匹配（完全锚定，等价于 `^...$`）
`!～`	正则不匹配

唯一的一元运算符 -

对一个标量使用 -，结果是一个符号取反的新标量

对一个瞬时向量使用 -，则向量中每一个元素的值都会被取反，但标签保持不变

对一个直方图样本使用 - 时，所有桶（bucket）的 population, count, sum 取反

直方图会被标记为 gauge histogram，因为 counter histogram 只能单调递增
任何包含负桶分布或负观测值的直方图只能用作中间结果。如果记录规则的最终结果为负值直方图，则规则评估将失败

算术二元运算符 +, -, *, /, %, ^

遵循 IEEE 754 浮点规则

https://en.wikipedia.org/wiki/IEEE_754

所有算术二元运算均忽略指标名称

标量 vs 标量：运算符应用于两个标量得到另一个标量

向量 vs 标量：对向量中的每个样本逐个适用运算符

对于直方图样本向量

* ：直方图 population, count, sum 均乘以标量

标量为负数，则生成的直方图被视为 gauge histogram，因为 counter histogram 只能单调递增

/ ：直方图样本必须作为除数

标量为负数，则生成的直方图被视为 gauge histogram，因为 counter histogram 只能单调递增

其他任何算术二元运算符均无结果，且相应的元素将从结果向量中移除

会记录到 info 级注解

向量 vs 向量：基于标签匹配进行逐对适用运算符，仅保留标签匹配的元素

浮点 vs 直方图：参考 向量 vs 标量 的直方图样本向量逻辑

仅 * 和 / 为有效运算

对于两个直方图样本向量，只有 + 和 - 操作有效

+ 和 - 操作通常只应用于 gauge histogram，但也允许将其应用于 counter histogram，以涵盖特定用例

需要特别注意以避免未对齐的计数器重置问题
PromQL 可以检测到某些计数器重置的不兼容性，并以警告级注释进行标记

两个 counter histogram 相加的结果仍然是 counter histogram，其他均为 gauge histogram

三角二元运算符 atan2

https://pkg.go.dev/math#Atan2

允许使用向量匹配对两个向量执行三角函数运算，但仅对浮点数样本进行运算

涉及直方图样本会从输出向量中移除相应的向量元素

会记录到 info 级注解

比较二元运算符 ==, !=, >, <, >=, <=

未使用 bool 修饰符时会保留左侧的度量名称

如果使用 on ，则会省略指标名称

如果使用 group_right ，则会保留右侧的指标名称，以避免冲突

标量 vs 标量：必须使用 bool 修饰符，否则无效；结果为 1（真）或 0（假）

向量 vs 标量：仅对向量中每个浮点样本应用比较，从结果向量中删除比较结果为假的向量元素

移除直方图样本会记录到 info 级注解

向量 vs 向量：基于标签匹配进行逐对比较，仅保留标签匹配且比较为真的元素

输出标签由匹配规则（如 on、group_left/right）决定
浮点 vs 直方图：无效，对应元素被移除

会记录到 info 级注解

直方图 vs 直方图：仅 == 和 != 有效，其他比较无效

逻辑二元运算符 and, or, unless

and（交集）

保留 vector1 中标签集在 vector2 中也存在的元素。
结果继承 vector1 的指标名和值。

or（并集）

包含 vector1 的所有元素，加上 vector2 中标签集不在 vector1 中出现的元素。

unless（补集 / 差集）

保留 vector1 中标签集在 vector2 中不存在的元素。
所有在两个向量中都存在的标签集会被丢弃。

聚合运算符对单个瞬时向量（instant vector）做聚合

默认聚合所有标签维度

by, without 修饰符可控制哪些标签参与分组

by 仅保留对应标签

<aggr-op> by (<labels>) (v)

without 丢弃标签

<aggr-op> without (<labels>) (v)

数值统计

sum(v)：求和

样本值必须要么均为浮点样本，要么均为直方图样本

avg(v)：平均值

样本值必须要么均为浮点样本，要么均为直方图样本

min(v) / max(v)：最小 / 最大

仅处理浮点样本

stddev(v) / stdvar(v)：总体标准差, 方差

仅处理浮点样本

quantile(φ, v)：φ 分位数（0–1）

仅处理浮点样本

排序抽样

topk(k, v), bottomk(k, v)：值最大 / 最小的 k 个

仅处理浮点样本
如果用于即时查询， topk 和 bottomk 分别返回按值降序或升序排列的序列
范围查询不进行排序

limitk(k, v)：随机选 k 个（实验性）

既适用于浮点样本，也适用于直方图样本

limit_ratio(r, v)：随机选 r 比例（实验性）

r 的取值范围为 +1 到 -1

当 r 为负值时，选择顺序会反转，这可用于选择互补样本

既适用于浮点样本，也适用于直方图样本

计数

group(v)：统计任意元素个数

在该时间点只要有任意值，返回结果值 1
既适用于浮点样本，也适用于直方图样本

count(v)：统计非空元素个数

在该时间点没有值，则返回空值
既适用于浮点样本，也适用于直方图样本

count_values(label, v)：按样本值本身分组计数，并写入指定 label

对 v 中每个 不同的样本值 输出一条时间序列，值为该样本值出现的次数

每个时间序列新增一个标签，名称为 label，值为样本值

既适用于浮点样本，也适用于直方图样本

向量匹配（Vector Matching）用于在标签集不同的时间序列之间建立匹配关系

两个匹配运算符：on, ignoring

ignoring 关键字允许在匹配时忽略某些标签

on 关键字允许在匹配时将考虑的标签缩小到给定列表

两个分组修饰符：group_left, group_right

高级用例，支持多对一/一对多向量匹配

只能用于比较与算术运算

默认情况下，and, or, unless 逻辑运算与右向量中的所有可能条目匹配

一对一匹配

左右两侧时间序列 标签完全一致 才能匹配

通过 on, ignoring 来决定哪些标签参与匹配

语法

<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>

样例

输入样本

一边有 code 标签一边没有

method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

忽略 code 标签进行比较

返回结果

多对一 / 一对多匹配

“一”侧的每个向量元素可以与“多”侧的多个元素匹配，group_<left|right> 决定哪个向量的基数更高

语法

<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>

<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>

<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>

<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>

样例

输入样本

一边有 code 标签一边没有

method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

左边标签多所以是 group_left

返回结果

PromQL 常用函数

参考资料

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

数值变换，直方图样本将被忽略

abs(v instant-vector)

ceil(v instant-vector)

floor(v instant-vector)

round(v instant-vector, to_nearest=1 scalar)

可选参数 to_nearest 允许指定样本值应四舍五入到的最接近的倍数，可以是小数

exp(v instant-vector)

sqrt(v instant-vector)

ln(v instant-vector)

特殊情况

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

log2(v instant-vector)

特殊情况同 ln()

log10(v instant-vector)

特殊情况同 ln()

sgn(v instant-vector) 符号函数（-1 / 0 / 1）

如果 v 为正，则为 1；如果 v 为负，则为 -1；如果 v 等于零，则为 0

clamp(v instant-vector, min scalar, max scalar) 将 v 中所有浮点样本的值限制在最小值 min 和最大值 max 之间

如果 min > max 则返回空向量

如果 min 或 max 为 NaN ，则浮点样品被钳制为 NaN

clamp_max(v instant-vector, max scalar) 将 v 中所有浮点样本的值限制在最大值 max 以内

clamp_min(v instant-vector, min scalar) 将 v 中所有浮点样本的值限制在最小值 min 以内

直方图数值变换

histogram_avg(v instant-vector)

histogram_count(v instant-vector)

histogram_sum(v instant-vector)

histogram_stddev(v instant-vector)

histogram_stdvar(v instant-vector)

histogram_fraction(lower scalar, upper scalar, b instant-vector)

histogram_quantile(φ scalar, b instant-vector)

速率 / 增量

rate(v range-vector) 计算范围向量 v 中时间序列每秒的平均增长率

只能用于 counter（包括浮点数和直方图）

当将 rate() 与一个对于聚合运算符或按时间聚合的函数（任何以 _over_time 结尾的函数），务必先调用 rate() ，然后再调用 aggregate

否则，当目标重启时， rate() 将无法检测到计数器重置

irate(v range-vector) 计算范围向量 v 中最后两个样本之间的时间序列的每秒瞬时增长率

只能用于 counter（包括浮点数和直方图）

只有在绘制波动剧烈、快速变化的计数器图表时才应使用 irate 。对于警报和缓慢变化的计数器，请使用 rate ，因为 rate 的短暂变化可能会重置 FOR 子句，而完全由罕见尖峰组成的图表难以解读

当将 irate() 与一个对于聚合运算符或按时间聚合的函数（任何以 _over_time 结尾的函数），务必先调用 irate() ，然后再调用 aggregate

否则，当目标重启时， irate() 将无法检测到计数器重置

delta(v range-vector) 计算范围向量 v 中每个时间序列元素的首尾值之差，并返回一个包含给定差值和相应标签的瞬时向量

示例：返回当前 CPU 温度与 2 小时前 CPU 温度的差值

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

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

只能用于 gauges

increase(v range-vector) 计算指定范围向量中时间序列的增量

只能用于 counter（包括浮点数和直方图）
是 rate(v) 的语法糖，主要用于提高代码的可读性

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

只能用于 gauges 且只适用于浮点数样本

delta 通过计算一个新的直方图来作用于直方图样本

时间函数

time() 返回表达式求值时的 UNIX 时间戳

timestamp(v instant-vector)

minute(v=vector(time()) instant-vector)

hour(v=vector(time()) instant-vector)

month(v=vector(time()) instant-vector)

year(v=vector(time()) instant-vector)

day_of_week(v=vector(time()) instant-vector) 返回每个时间戳对应的本周日期

day_of_month(v=vector(time()) instant-vector) 返回每个时间戳对应的本月日期

day_of_year(v=vector(time()) instant-vector) 返回每个时间戳对应的年份天数

days_in_month(v=vector(time()) instant-vector) 返回每个时间戳所在月份的天数

线性预测 predict_linear / 双指数平滑 double_exponential_smoothing

predict_linear(v range-vector, t scalar) 基于范围向量 v ，使用简单线性回归预测 t 秒后的结果

至少包含两个浮点数样本
只能与计量器一起使用，并且仅适用于浮点型样本

double_exponential_smoothing(v range-vector, sf scalar, tf scalar) 为范围向量 v 内的每个浮点时间序列生成一个平滑值

通过 --enable-feature=promql-experimental-functions 启用
sf 和 tf 必须介于 0 和 1 之间

平滑因子 sf 越低，旧数据的重要性就越高
趋势因子 tf 越高，数据中的趋势考虑得就越多

只能与计量器一起使用，并且仅适用于浮点型样本

变化计数 changes(), reset()

changes(v range-vector) 返回其值在指定时间范围内发生变化的次数，并以瞬时向量的形式返回

点数样本后跟直方图样本（反之亦然）计为一次变化
计数器直方图样本后跟数值完全相同的计量器直方图样本（反之亦然）不计为一次变化

resets(v range-vector) 返回指定时间范围内计数器重置的次数，以瞬时向量的形式表示

只能用于计数器（浮点数和直方图均适用）
两个连续浮点样本之间的任何值减少都被视为计数器重置
原生直方图中的任何桶（包括零桶）或观测值计数的减少都构成计数器重置
任何先前填充的桶的消失、零桶宽度的减小，或任何不兼容的分辨率降低的模式更改也构成计数器重置
点数样本后跟直方图样本（反之亦然）计为一次变化
计数器直方图样本后跟仪表直方图（反之亦然）也计为一次变化

但首先就不应该对仪表直方图使用 resets()

排序

sort(v instant-vector)

sort_desc(v instant-vector)

sort_by_label(v instant-vector, label string, ...)

通过 --enable-feature=promql-experimental-functions 启用

sort_by_label_desc(v instant-vector, label string, ...)

通过 --enable-feature=promql-experimental-functions 启用

缺失检测 absent(), absent_over_time()

absent(v instant-vector) 传递的向量没有元素返回一个值为 1 的单个元素向量，非空则返回空向量

absent_over_time(v range-vector) 传递的范围向量没有元素返回一个值为 1 的单个元素向量，非空则返回空向量

标签操作 label_join, label_replace, info

label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)

使用 separator 连接所有 src_labels 的所有值并返回带有标签 dst_label 的时间序列，该标签包含合并后的值

label_join 样例

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

返回一个向量，其中每个时间序列都有一个名为 foo 标签，并在其后添加值 a,b,c

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

label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)

将正则表达式 regex 与标签 src_label 的值进行匹配

正则表达式中的捕获组可以用 $1 、 $2 等引用
正则表达式中的命名捕获组可以用 $name 引用（其中 name 是捕获组的名称）

如果匹配，则返回的时间序列中标签 dst_label 的值将是 replacement 的扩展值，并保留输入中的原始标签；如果不匹配，则返回原时间序列

label_replace 样例

label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P<name>.*):(?P<version>.*)")

将返回新增标签为 foo ，其值为 a 的时间序列

up{job="api-server",service="a:c",foo="a"}

info(v instant-vector, [data-label-selector instant-vector]) 针对 v 中的每个时间序列，查找所有匹配 identifying labels 的 info 指标序列，将 data labels 添加到 v 中

通过 --enable-feature=promql-experimental-functions 启用
data-label-selector 可选，用于约束要考虑哪些信息序列以及要将哪些数据标签添加到 v
详见下面的 info 指标部分

类型转换 scalar(), vector()

scalar(v instant-vector) 给定一个只包含一个浮点数元素的瞬时向量，返回标量值

如果输入向量中没有恰好一个浮点样本元素， scalar 将返回 NaN

vector(s scalar) 将标量 s 转换为浮点样本，返回只包含一个浮点数元素的瞬时向量，不包含任何标签

PromQL 聚合函数

PromQL 聚合函数对直方图样本的处理方式

count_over_time, first_over_time, last_over_time, present_over_time() 处理同浮点数

avg_over_time(), sum_over_time() 处理方式与各自的聚合运算符相对应

其他函数忽略直方图样本

仅包含直方图的样本静默移除
混合包含浮点数和直方图的样本，仅处理浮点样本

移除直方图样本会记录到 warn 级注解

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

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 则可以

first_over_time(range-vector) 指定区间内最古老的样本
mad_over_time(range-vector) 指定区间内所有浮点样本的中位数绝对偏差
ts_of_last_over_time(range-vector) 指定时间间隔内最后一个样本的时间戳
ts_of_first_over_time(range-vector)
ts_of_min_over_time(range-vector)
ts_of_max_over_time(range-vector)

PromQL 三角函数，忽略输入向量中的直方图样本

acos(v instant-vector)

acosh(v instant-vector)

cos(v instant-vector)

cosh(v instant-vector)

asin(v instant-vector)

asinh(v instant-vector)

sin(v instant-vector)

sinh(v instant-vector)

atan(v instant-vector)

atanh(v instant-vector)

tan(v instant-vector)

tanh(v instant-vector)

deg(v instant-vector) 将 v 中的所有浮点样本的弧度转换为度

rad(v instant-vector) 将 v 中的所有浮点样本的度数转换为弧度

pi()

PromQL 中的正则表达式均使用 RE2 语法，与 Go 一致

https://github.com/google/re2/wiki/Syntax

https://regex101.com/

选择 Golang

PromQL 其他特性

PromQL join 查询将一个指标的标签集附加到另一个指标

参考资料

https://www.robustperception.io/left-joins-in-promql/

https://ypereirareis.github.io/blog/2020/02/21/how-to-join-prometheus-metrics-by-label-with-promql/

与 SQL join 相似

区别在于，PromQL 的二元运算符作用于表达式，而 SELECT 语句作用于表

a * on (foo, bar) b 在语义上等价于 SQL 的内连接

SELECT a.value * b.value, a.foo, a.bar FROM a INNER JOIN b ON (a.foo == b.foo AND a.bar == b.bar)

a * on (foo, bar) group_left(baz) b 在语义上等价于 SQL 的左连接

SELECT a.value * b.value, a.*, b.baz FROM a JOIN b ON (a.foo == b.foo AND a.bar == b.bar)

对于不可避免的字段缺失可以使用 or on (<labels>) <self>

a * on (foo, bar) group_left(baz) b or on (foo, bar) a 在语义上等价于 SQL 的左全连接
SELECT a.value * COALESCE(b.value, 1), a.*, b.baz FROM a LEFT OUTER JOIN b ON (a.foo == b.foo AND a.bar == b.bar)

样例：添加 target_info 时间序列的 k8s_cluster_name 标签

rate(http_server_request_duration_seconds_count[2m]) * on (job, instance) group_left (k8s_cluster_name) target_info

info 指标和 identifying 标签

参考资料

https://grafana.com/blog/how-to-use-promql-joins-for-more-effective-queries-of-prometheus-metrics-at-scale/#info-metrics

info 指标是一种携带元数据（metadata）而非数值指标的特殊的时间序列

用于编码高基数标签值
info 指标本身用处不大，但其标签与其他指标结合使用则很有用

比如下面的 node_uname_info 就是一种由 node_exporter 导出的 info 指标，值始终为 1

node_uname_info{cluster="dev-us-central-0", domainname="(none)", instance="localhost", job="default/node-exporter", machine="x86_64", namespace="default", nodename="dev-host-1", release="4.19.150+", sysname="Linux", version="#1 SMP Tue Nov 24 07:54:23 PST 2020"} 1

info 指标的标签可以逻辑地分为 identifying labels 和 data labels

注意，Prometheus 的时间序列标识概念始终包含所有标签，这里只是为了方便定义 info 指标的标识

identifying labels 是用于唯一区分 info 指标时间序列的标签子集

如 {job="api", instance="localhost:9090"}
通过 identifying labels 来帮助 info 指标附加到 non-info 指标时间序列

data labels 是附加的、描述性的标签，代表元数据的键值对

用来附加到 non-info 指标时间序列上

通过 info 函数可以更加简单地将 info 指标的标签集附加到其他指标上

通过 --enable-feature=promql-experimental-functions 启用

info 只扫描匹配 (job, instance) 的 target_info

info 始终选择最新样本的 target_info

resource attributes 变化，旧的 target_info 在 5 分钟 lookback 内仍然存在，此时同时匹配新旧 target_info 会报错 many-to-many matching not allowed

info 查询示例

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

info 找到同 job + instance 的 target_info，然后把 k8s_cluster_name label 附加到结果上

手动 join 示例

rate(http_server_request_duration_seconds_count[2m]) * on (job, instance) group_left (k8s_cluster_name) target_info

Staleness（数据过期机制）

Prometheus 查询时的采样时间点独立于实际数据时间戳

默认使用 5 分钟 lookback 窗口，即取 最近 5 分钟内最新样本 作为该时间点的值

可以通过特性 --query.lookback-delta 来调整
或者通过 lookback_delta 参数在单个查询中进行覆盖

当一个时间序列不再被采集（如目标下线、指标停止上报）：

该序列会被标记为 stale（过期）
过期后，查询将不再返回该序列（即使它曾经存在）
在图表中，该序列会在最后一个有效样本处消失
如果之后有新的有效样本，则会重新上线

若 Exporter 自带时间戳（非 Prometheus 抓取时间），Prometheus 无法立即判断 series 已消失

默认仍保留最后的值，持续一个 lookback 窗口
可通过 track_timestamps_staleness 调整

避免慢查询与系统过载

先在 Table 模式下构建查询，确保结果只有数百个时间序列（而非数千）

先过滤（label matcher）或聚合（sum, avg），再切到 Graph 模式

对高频复杂查询，使用 Recording Rule 预计算，而非实时执行

PromQL 数据模型

PromQL 语法规范

PromQL 其他特性

白鸟3