PromQL解析器中持续时间字面量的括号在往返序列化时丢失

概述

在Prometheus的PromQL查询语言解析器中，查询字符串的解析与序列化（Expr.String()）应具备“往返一致性”（round-trip consistency）。这意味着将一个查询字符串解析为抽象语法树（AST）后，再将其序列化回字符串时，应得到一个语义等价的查询。本页面描述了一个特定的解析器缺陷：当一个被括号包裹的简单数字字面量（如 (5)）用在持续时间表达式位置（如 offset 或范围括号 []）时，序列化过程会错误地丢失括号。这一问题会影响查询的准确表示和调试，对于依赖精确查询表示的SRE工作流而言需要关注。

核心概念

PromQL 解析器: 负责将文本形式的PromQL查询转换为可供Prometheus引擎执行的内部数据结构（AST）。
往返序列化 (Expr.String()): 将解析器生成的AST对象重新转换为PromQL文本字符串的过程。理想的往返序列化应能精确还原原始查询的语义。
*NumberLiteral: AST节点，代表一个简单的数值（如 5）。当它被括号包裹时，如 (5)，在普通表达式上下文中，它会由 *ParenExpr 节点包装，该节点在序列化时负责输出括号。
*DurationExpr: AST节点，代表一个持续时间表达式（如 5m、5m + 1s）。它拥有一个 Wrapped 字段，用于指示该表达式是否被括号包裹，从而在序列化时能正确输出括号。
持续时间表达式上下文: 指的是语法上要求持续时间值的位置，例如查询 foo offset 5m 中的 5m，或 foo[5m] 中的范围参数。

实践

此问题在启用了 ExperimentalDurationExpr: true 配置的Prometheus环境中表现明显。其核心在于解析器对“持续时间上下文”中的括号处理逻辑存在不一致性。

问题表现

当解析器遇到一个单独的数字字面量（如 5）被括号包裹并用在持续时间上下文中时，它可能会生成一个直接的 *NumberLiteral 节点，而非预期的、携带括号信息的 *DurationExpr 节点。由于 *NumberLiteral 节点没有存储括号信息，序列化时括号就会丢失。

下表展示了问题重现的具体案例：

输入查询	`Expr.String()` 输出	是否保留括号	说明
`foo offset (5)`	`foo offset 5s`	否	括号丢失，单位被推断为`s`。
`foo offset +(5)`	`foo offset 5s`	否	正号和括号均丢失。
`foo offset -(5)`	`foo offset -5s`	否	负号被保留，但括号丢失。
`foo offset (5m)`	`foo offset 5m`	否	括号丢失。
`foo[(5s)]`	`foo[5s]`	否	范围括号内的括号丢失。

作为对比，以下情况可以正确往返序列化：

输入查询	`Expr.String()` 输出	是否保留括号	说明
`(5)`	`(5)`	是	非持续时间上下文，由 `*ParenExpr` 处理。
`-(5)`	`-(5)`	是	非持续时间上下文。
`+(5)`	`+(5)`	是	非持续时间上下文。
`(5) + 1`	`(5) + 1`	是	非持续时间上下文。
`foo offset (5m + 1m)`	`foo offset (5m + 1m)`	是	多段持续时间表达式，使用 `*DurationExpr` 节点。
`foo offset -(5m + 1m)`	`foo offset -(5m + 1m)`	是	多段持续时间表达式。
`foo[(5s + 1s)]`	`foo[(5s + 1s)]`	是	多段持续时间表达式。

根本原因

差异的关键在于AST节点类型：

多段持续时间表达式（如 5m + 1s）在持续时间上下文中会生成 *DurationExpr 节点。该节点具有一个 Wrapped 字段，解析器能据此记录括号信息，确保序列化时能正确还原。
简单的数字字面量（如 5）在持续时间上下文中，当前实现可能直接生成 *NumberLiteral 节点。该节点没有类似 Wrapped 的字段来存储括号信息，导致序列化时信息丢失。

验证与影响

验证：SRE工程师可以通过编写单元测试或在Prometheus的调试工具中输入上述查询，对比原始输入和 Expr.String() 输出来验证此问题。
影响：虽然从Prometheus引擎执行角度看，foo offset (5) 和 foo offset 5s 通常语义等价，但括号的丢失会影响：
- 查询的可读性与意图：原始查询中的显式分组意图（括号）在输出中消失。
- 调试与日志分析：当查询被记录或输出时，其形式与原始输入不同，可能引起混淆。
- 配置管理：如果PromQL查询存储在配置文件中并经过解析-序列化流程，其文本表示可能发生意外变化。

SRE 要点

与可靠性的关联

此问题直接关系到查询可靠性。虽然可能不直接导致服务中断，但破坏了数据表示的一致性这一基本原则。在自动化运维、GitOps配置管理、或复杂的查询模板生成场景中，不一致的序列化结果可能导致配置漂移或难以追踪的差异。

最佳实践与注意事项

意识：在编写或调试涉及括号的持续时间表达式时，意识到此解析器行为。如果括号对查询意图至关重要（例如在复杂表达式中进行分组），需验证其在解析后是否被保留。
测试：在开发依赖于PromQL查询精确文本表示的工具链时，应将此边界情况纳入测试用例。
关注更新：此问题已在GitHub Issue #18770中被跟踪。SRE团队应关注Prometheus官方发布，以确认后续版本是否修复了此缺陷。修复可能涉及修改解析逻辑，确保在持续时间上下文中为简单的带括号数字字面量生成适当的AST节点。