3. Recording Rules 语法详解：PromQL 表达式、规则文件格式与 YAML 结构

Recording Rules 的核心价值在于“预计算 + 存储”，而这一切的起点是正确的语法。本章将深入拆解 Recording Rule 的三大语法支柱：PromQL 表达式的编写规范、规则文件格式的字段定义，以及YAML 结构的层级约束。掌握这些语法细节，是避免配置错误、提升规则可维护性的关键。

3.1 规则文件整体结构：YAML 顶层字段

一个标准的 Recording Rule 文件以 .yml 或 .yaml 结尾，顶层必须包含 groups 列表。每个 group 是一组规则的逻辑集合，共享相同的评估间隔。

字段	类型	是否必填	说明
groups	list	是	规则组列表，至少包含一个组
name	string	是	规则组名称，在文件中必须唯一
interval	duration	否	组内规则的评估间隔，默认继承全局 evaluation_interval
rules	list	是	规则列表，包含 record 或 alert 条目

3.2 Recording Rule 字段详解

每个 Recording Rule 条目由 record、expr 和可选的 labels 组成。以下为完整字段定义：

字段	类型	是否必填	说明
record	string	是	新时间序列的名称，必须符合 Prometheus 指标命名规范
expr	string	是	PromQL 表达式，计算结果将存储为新的时间序列
labels	map	否	额外添加或覆盖的标签键值对，用于丰富新序列的维度

3.3 PromQL 表达式编写规范

PromQL 是 Recording Rule 的灵魂。表达式必须返回一个瞬时向量（instant vector），因为 Recording Rule 只能存储瞬时向量类型的结果。以下为常见表达式模式：

• 聚合运算：sum(rate(http_requests_total[5m])) by (service)
• 比率计算：avg(rate(http_requests_total[5m])) / avg(rate(http_requests_total[5m])) offset 5m
• 分位数计算：histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service))
• 布尔运算：(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes > 0.8

3.4 完整 YAML 文件示例

groups:
  - name: example_recording_rules
    interval: 30s
    rules:
      - record: job:http_requests:rate5m
        expr: sum(rate(http_requests_total[5m])) by (job)

      - record: instance:node_cpu:utilization
        expr: (1 - avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance)) * 100

      - record: service:request_duration:p95
        expr: histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service))
        labels:
          quantile: "0.95"

3.5 规则文件语法校验

Prometheus 提供了 promtool 工具来验证规则文件的语法正确性：

# 检查规则文件语法
promtool check rules /path/to/rules.yml

# 在 Prometheus 容器内执行
docker exec <container_name> promtool check rules /etc/prometheus/rules.yml

常见错误包括：YAML 缩进错误、PromQL 语法错误、record 名称不符合规范、expr 返回非瞬时向量类型等。

3.6 Recording Rule 执行流程 SVG 图

3.7 规则文件分层组织 SVG 图

interval，基础设施层可设为 15s，聚合层设为 60s • 通过 rule_files 在 Prometheus 主配置中引入多个文件

3.8 常见语法错误与排查

错误类型	典型表现	解决方案
YAML 缩进错误	Prometheus 启动报错 yaml: line X: did not find expected key	使用 2 空格缩进，统一层级，避免 Tab 与空格混用
PromQL 语法错误	规则评估失败，日志显示 parse error	在 Prometheus UI 的 Graph 页面先测试表达式，确认返回瞬时向量
指标名称冲突	新规则覆盖已有指标，导致查询结果异常	使用命名空间前缀，如 team:metric 或 layer:metric
标签覆盖不当	聚合后丢失关键维度，导致数据粒度变粗	在 labels 中只添加必要标签，避免覆盖原始标签