3. 录制规则核心概念：recording rule 的定义、rule_group 结构、record 字段与 expr 字段详解、labels 字段的作用

录制规则（Recording Rule）是 PromQL 水位治理中最核心的工程化手段。它允许你将一个频繁使用或计算昂贵的 PromQL 表达式预先计算并存储为一条新的时间序列，从而降低查询延迟、减少计算压力，并为水位监控提供稳定的指标基座。本节将系统拆解录制规则的四个关键维度：定义、分组结构、核心字段语义以及标签控制。

3.1 什么是 Recording Rule

Recording Rule 本质上是一个“预计算 + 存储”的声明式配置。当 Prometheus 服务器加载规则文件后，会按照指定的评估周期（evaluation_interval）反复执行 expr 中的 PromQL 表达式，并将结果写入一个新的时间序列，该序列的名称由 record 字段指定。

3.2 rule_group 结构：规则的容器与调度单元

所有录制规则必须归属于一个 rule_group。一个规则文件可以包含多个 rule_group，每个 rule_group 拥有独立的评估间隔和规则列表。这种分组机制为不同重要等级或不同计算频率的规则提供了隔离能力。

groups:
  - name: node_cpu_water_level
    interval: 30s
    rules:
      - record: node:node_cpu_utilization:ratio_avg5m
        expr: avg by (instance) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))
        labels:
          level: "watermark"
      - record: node:node_cpu_utilization:ratio_avg30m
        expr: avg by (instance) (rate(node_cpu_seconds_total{mode!="idle"}[30m]))
        labels:
          level: "watermark"

3.3 record 字段与 expr 字段详解

record 和 expr 是录制规则的两个必填字段，它们共同定义了“存储什么”和“如何计算”。

record 字段：输出指标的名称

• 命名规范：推荐使用 namespace:metric_name:suffix 的三段式命名法，例如 node:node_cpu_utilization:ratio_avg5m。命名空间（如 node）避免跨团队冲突，后缀（如 ratio_avg5m）明确聚合类型与窗口。
• 唯一性：同一 Prometheus 实例内，record 名称不能与已有的指标名称或其它录制规则名称重复，否则会导致数据覆盖或查询歧义。
• 标签继承：新生成的时间序列会保留 expr 结果中的所有标签，除非在 labels 字段中显式覆盖或添加。

expr 字段：PromQL 表达式

• 表达式限制：必须返回一个瞬时向量（instant vector），不能是标量、字符串或范围向量。如果表达式返回范围向量，需要使用 avg、max、quantile 等聚合函数或子查询将其转换为瞬时向量。
• 性能考量：避免在 expr 中使用 offset 过大的时间偏移或未经聚合的高基数标签（如 pod、device），否则录制规则本身会成为性能瓶颈。
• 水位场景典型表达式：

# 水位场景：计算每个实例的 CPU 利用率 5 分钟平均比率
expr: avg by (instance) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))

# 水位场景：计算集群级别的内存使用率 99 分位
expr: quantile by (cluster) (0.99, (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes))

# 水位场景：计算请求错误率（5 分钟滑动窗口）
expr: sum by (service) (rate(http_requests_total{status=~"5.."}[5m])) / sum by (service) (rate(http_requests_total[5m]))

3.4 labels 字段的作用：标签控制与覆盖

labels 字段是一个可选的映射表，用于在录制规则输出时添加、修改或删除标签。它不会影响原始指标，只作用于新生成的时间序列。

3.5 录制规则核心概念关系图

下图展示了录制规则从配置加载到时间序列写入的完整数据流，以及 rule_group、record、expr、labels 四个核心要素之间的协作关系。

3.6 核心字段对比总结

下表从字段属性、必填性、数据类型、典型用途四个维度对四个核心概念进行横向对比，便于快速查阅。

3.7 常见陷阱与避坑指南