PromQL 查询格式化与验证器
指导
即时格式化和验证 Prometheus PromQL 查询
PromQL 查询格式化器与验证器会整理您针对 Prometheus 及其他兼容的时间序列数据库编写的查询。将指标表达式粘贴到输入区域，该工具会规范化二元运算符周围的空格，当查询变长时，会将聚合操作、函数调用和标签匹配器分别置于独立行，并在您将查询粘贴到仪表板或告警规则之前，指出未匹配的括号、不匹配的花括号、缺失的持续时间及其他语法问题。所有操作均在您的浏览器本地运行，因此通常暴露内部指标名称和标签的查询永远不会离开您的设备。
如何使用
- 将您的 PromQL 查询粘贴到输入区域，或使用文件选择器上传一个
.promql或文本文件。 - 选择缩进宽度——2个空格、4个空格或一个实际的制表符字符——用于多行展开。
- 设置最大行长度。函数调用、标签匹配器集合和低优先级布尔运算符（
and,or,unless）一旦格式化后的行长度超过此宽度，就会换到下一行。 - 切换 始终拆分 如果您希望每个聚合操作、函数调用参数列表和标签匹配器集合都独立成行，无论其长度如何。
- 切换 作为记录规则包装 并提供一个指标名称（例如
job:http_errors:rate5m）以将格式化的查询作为可直接粘贴的 Prometheus 记录规则输出为 YAML 格式。 - 复制格式化后的输出或将其下载为一个
.promql文件。
特征
- PromQL 意识的空格处理 – 在算术、比较和布尔运算符周围插入一个空格，同时保持标签匹配器在括号内的紧凑性。
{ }braces. - 智能多行布局 – 在长查询中，首先在函数参数边界处、然后在单个标签匹配器处进行断行，以确保结果易于扫描。
and/or/unlessfirst, then at function argument boundaries, then at individual label matchers so the result remains easy to scan. - 聚合和向量匹配支持 – 识别
sum,avg,topk,quantile及其变体，以及by,without,on,ignoring,group_left且group_right修饰符。 - 持续时间与子查询解析器 – 将复合范围如
1h30m和子查询如[5m:1m]解析为单个单元，以确保它们不会在令牌中间被分割。 - 语法验证 – 检测未匹配的括号、方括号和花括号，不匹配的开闭括号，无效的标签匹配器体，无效的下标范围和未终止的字符串，每个问题均附带行号报告。
- 记录规则导出 – 可选地将格式化的查询包装为 Prometheus YAML 记录规则块，使用 YAML 字面量块标量处理多行表达式，以保留缩进。
常见用例
- 清理从 Grafana 仪表板编辑器复制的临时 Prometheus 查询，以便在仪表板或告警规则中提交。
- 为代码审查准备 PromQL 表达式——长的错误率或饱和查询在每个分支独立成行后，会变得易于阅读的差异。
- 发现细微的语法错误（缺少持续时间、多余的逗号、未关闭
{在编辑标签匹配器后）而无需通过实时 Prometheus 实例进行往返操作。 - 将原始查询转换为 Prometheus 记录规则 YAML，用于预聚合管道。
- 教授 PromQL——标准化的输出使操作符优先级和聚合分组对学习该语言的读者立即显而易见。
常问问题
-
什么是 PromQL？
PromQL（Prometheus 查询语言）是 Prometheus 监控系统及其兼容后端（如 Thanos、Mimir、Cortex、VictoriaMetrics 和 Amazon Managed Service for Prometheus）所使用的读取端查询语言。它专为时间序列数据设计：每个表达式评估为瞬时向量、范围向量、标量或字符串，且操作符理解标签集匹配、分组和时间范围内的速率语义，而通用 SQL 无法实现。
-
瞬时向量和范围向量有何区别？
瞬时向量是在单个时间点上的时间序列样本集合——例如，所有匹配 http_requests_total 的系列的最新值。范围向量是某个持续时间窗口内的样本集合，以带括号的持续时间形式书写，如 [5m]。范围向量无法直接显示；它们是 rate()、increase() 和 avg_over_time() 等函数的输入，这些函数将窗口压缩回瞬时向量。
-
`by` 和 `without` 在聚合中有什么区别？
两者都修改聚合操作（如 sum 和 avg）的分组行为。`by` 子句仅保留列出的标签，因此 sum by (job) (rate(...)) 会消除所有标签除了 job。`without` 子句保留所有标签除了列出的标签，因此 sum without (instance) (rate(...)) 会保留所有其他维度。等效的分组可以以任意方式书写；团队通常选择一种方式以保持一致性。
-
什么是记录规则，为什么要预先计算一个？
记录规则是 Prometheus 定期评估的命名 PromQL 表达式，其结果作为新指标写回。预先计算复杂表达式（例如，按服务的 5 分钟错误率）可以让仪表板和告警直接查询结果，而不是在每次刷新时重新计算整个表达式。通常，记录规则的命名遵循 level:metric:operation 模式，例如 job:http_requests_errors:rate5m，以便从指标名称中直接理解其含义。
-
`on`、`ignoring`、`group_left` 和 `group_right` 做什么？
这些关键字控制 PromQL 在二元操作的两侧之间匹配系列的方式。默认情况下，Prometheus 要求两侧具有相同的标签集；`on(label, ...)` 和 `ignoring(label, ...)` 允许限制或放宽连接键。`group_left` 和 `group_right` 将匹配转换为一对一或多对一的连接，将高基数侧的标签复制到结果中。它们相当于时间序列数据的 SQL 连接提示。
