📚 课程目录第4章录制规则配置文件

4. 录制规则配置文件：rules.yml 结构、加载与配置

水位录制规则的核心载体是 Prometheus 的 Recording Rules 配置文件。本章将深入剖析 rules.yml 的文件结构、groups 配置规范、规则文件的加载机制以及 Prometheus 主配置中 rule_files 字段的用法。掌握这些基础，是设计可维护、高性能录制规则的前提。

4.1 rules.yml 文件结构

一个标准的录制规则文件采用 YAML 格式，顶层必须包含 groups 列表。每个 group 下包含一组规则（rules），每条规则由 record、expr 和可选的 labels 组成。

  核心结构： 一个 rules.yml 文件可以包含多个 group，每个 group 可以包含多条规则。Prometheus 按 group 为单位进行规则评估。

# rules.yml 示例
groups:
  - name: example_high_cpu_group
    interval: 30s
    rules:
      - record: node:cpu_utilization:avg5m
        expr: avg by (instance) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))
        labels:
          team: "infra"
      - record: node:memory_usage:ratio
        expr: (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100

  - name: example_latency_group
    interval: 60s
    rules:
      - record: http:request_duration_seconds:p99
        expr: histogram_quantile(0.99, sum by (le, job) (rate(http_request_duration_seconds_bucket[5m])))

4.2 groups 配置详解

groups 是规则文件的组织单元，其配置字段直接影响规则的评估行为和性能。下表列出了 groups 的关键配置项：

字段	类型	是否必填	说明
`name`	string	是	组名称，在 Prometheus 实例内必须唯一。建议使用有意义的命名，如 `node_resource_rules`。
`interval`	duration	否	组内规则的评估周期。如果未指定，则继承全局 `evaluation_interval`（默认 15s）。
`limit`	integer	否	组内所有规则产生的告警或记录数据点数量的上限。用于防止意外的高基数爆炸。
`rules`	list	是	规则列表，包含 `record`、`expr`、`labels` 等子字段。

最佳实践： 将具有相同评估周期或业务逻辑的规则放在同一个 group 中。例如，将所有 5 分钟粒度的 CPU 相关规则放在 cpu_5m_rules 组，将 1 小时粒度的容量规划规则放在 capacity_1h_rules 组。这有助于隔离故障和优化评估性能。

4.3 规则文件加载方式

Prometheus 通过主配置文件中的 rule_files 字段指定规则文件的路径。加载机制遵循以下流程：

启动加载： Prometheus 启动时，读取 rule_files 中列出的所有文件，解析并加载到内存。
热重载： 通过向 Prometheus 进程发送 SIGHUP 信号或调用 /-/reload HTTP 端点，可以动态重新加载规则文件，无需重启服务。
文件通配符： rule_files 支持 Glob 模式（如 rules/*.yml），方便批量管理多个规则文件。
语法校验： 加载时 Prometheus 会校验 YAML 语法和 PromQL 表达式合法性。加载失败时，Prometheus 会拒绝启动或重载，并记录错误日志。

注意： 热重载仅加载新增或修改的规则文件。如果删除了某个规则文件，Prometheus 不会自动移除已加载的规则，需要手动重启或重载整个配置。建议在删除规则文件前，先清空文件内容并重载一次。

4.4 Prometheus 配置中 rule_files 字段

在 Prometheus 主配置文件 prometheus.yml 中，rule_files 是一个列表字段，用于声明规则文件的路径。其配置方式如下：

# prometheus.yml 片段
global:
  scrape_interval: 15s
  evaluation_interval: 15s  # 全局规则评估间隔

rule_files:
  - "rules/node_rules.yml"
  - "rules/application_rules/*.yml"
  - "rules/capacity/*.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['localhost:9093']

rule_files 的路径是相对于 Prometheus 进程的工作目录或配置文件中指定的路径。推荐将规则文件统一存放在 rules/ 目录下，并按功能模块拆分，便于维护和版本控制。

4.5 规则文件加载与评估流程

下图展示了从配置文件加载到规则评估的完整流程：

4.6 多文件组织策略

在生产环境中，推荐按以下维度拆分规则文件，以提升可读性和管理效率：

文件名称	包含内容	评估间隔
`node_rules.yml`	节点级别资源水位规则（CPU、内存、磁盘、网络）	30s
`application_rules.yml`	应用层延迟、错误率、吞吐量规则	15s
`capacity_rules.yml`	容量规划与长期趋势规则（1h/1d 粒度）	5m
`slo_rules.yml`	SLO 相关的水位与燃烧速率规则	1m

组织建议： 将规则文件纳入版本控制（如 Git），并在 CI/CD 流程中加入 Prometheus 规则语法检查工具（如 promtool check rules），确保规则变更的可靠性和可追溯性。