PromQL 是用于选择和聚合 Prometheus 时间序列的嵌套函数式语言。每个查询是一棵表达式树:叶子是选择器,节点是函数与运算符,根是标量、瞬时向量、区间向量或字符串。类型正确性决定查询是否有效,基数意识决定查询是否高效。该技能是编写 PromQL 查询的权威参考,适用于仪表盘、告警、记录规则与探索;指标埋点(指标类型、命名、标签、导出器)由配套的 backend/prometheus 技能负责。
主要能力:选择器与数据类型(瞬时/区间向量选择器、标签匹配 =、!=、=~、!~、时长、offset 与 @ 修饰符、陈旧性);运算符(算术、比较、逻辑/集合、向量匹配 on/ignoring/group_left/group_right、聚合运算符、by/without、优先级);函数目录(计数器族、仪表函数、经典与原生直方图、*_over_time、存在性检查、标签操作、数学、时间、类型转换、排序);原生直方图(检测、histogram_quantile、原生专用函数、迁移模式);子查询(语法、分辨率与对齐、与记录规则的取舍);优化与陷阱(基数、rate-of-gauge、先聚合后 rate、比率平均、计数器重置、窗口大小);记录与告警规则(规则文件结构、level:metric:operations 命名、告警语法、for/keep_firing_for、模板)。
使用方式:按需阅读对应参考文件后再编写查询。核心规则包括:rate() 只用于计数器,仪表用 delta()、idelta()、deriv();先 rate() 再聚合,即 sum(rate(x[5m])),不可写成 rate(sum(x)[5m]);比率要分别对分子分母求和后再相除;不要对 summary 分位数取平均;聚合经典直方图桶时必须保留 le;区间至少为抓取间隔的 4 倍且不小于 1m;告警用 rate() 而非 irate();多数聚合优先用 without 而非 by;offset 必须紧跟在选择器之后;尽早用标签匹配器过滤。
适用场景:编写仪表盘查询、告警规则、记录规则以及临时探索。限制:字符串不能作为查询结果;区间向量不能直接绘图,必须经函数转为瞬时向量;子查询会在每个分辨率步重跑内部表达式,开销大,昂贵表达式应转为记录规则,且避免在记录规则内使用子查询。具体参考文件路径与更多细节以资料为准,其余未提供。