Recording Rules 是 Prometheus 的预计算机制，用于将高频复杂 PromQL 提前聚合为新指标以降低查询延迟；适用于仪表盘卡顿、重复计算、降维聚合和统一口径场景。
记录规则（Recording Rules）是 Prometheus 实现指标聚合的核心机制，本质是“预计算”而非缓存——它把高频、复杂或长时窗的 PromQL 表达式提前算好，存成新的时间序列指标，后续直接查这个新指标即可，大幅降低查询延迟和资源压力。
什么时候该用 Recording Rules？
当出现以下情况时，就该考虑引入记录规则：
- 仪表盘刷新慢、Grafana 图表加载超时（尤其在查 1h+ 时间范围时）
- 同一 PromQL 表达式被多个面板、告警或 API 反复调用（如
rate(http_requests_total[5m]) by (job)） - 需要对原始高基数指标做降维聚合，再供下游使用（例如按 namespace 或 cluster 汇总容器 CPU）
- 想统一指标口径，避免不同团队写法不一致导致统计偏差（比如 10 个面板各自算一遍
sum(rate(...))）
怎么写一条有效的记录规则？
规则语法简洁，但关键细节不能错：
-
record 字段必须是合法指标名：只含字母、数字、下划线，不能带花括号或标签，例如
job:http_requests_rate_5m✅，http_requests_rate_5m{job="api"}❌ -
expr 字段写完整 PromQL：支持聚合、函数、过滤，但不支持子查询；标签逻辑在 expr 中处理，比如
sum(rate(http_requests_total{job=~"api|backend"}[5m])) by (job) -
命名建议带语义前缀：如
namespace:container_cpu_usage_seconds_total:sum_rate，便于理解来源和含义 -
避免高基数陷阱：原始指标若含动态 label（如
request_id、user_id），先用without或by显式降维，否则会爆炸生成海量新时间序列
如何确认规则真正生效？
定义完不等于跑起来，必须验证三个环节：
-
语法检查：用
promtool check-rules /path/to/rules.yml确保无报错，返回值为 0 -
配置重载：发送
SIGHUP或调用/-/reload接口，查看日志确认规则组加载成功 -
数据验证：在 Prometheus 表达式浏览器中直接查
job:http_requests_rate_5m，看是否有样本；同时查prometheus_rule_evaluations_total{rule_group="your-group-name"}是否持续增长
常见误区与避坑点
很多性能问题没改善，其实是掉进了这些坑：
- 写了 recording rule，但 Grafana 面板、告警规则仍查原始表达式——Prometheus 不会自动替换，必须手动改查询语句
- record 名与已有指标冲突，导致写入失败或覆盖关键指标（可用
count({__name__=~".+"})快速排查重复名） - evaluate_interval 设置过短（如 5s），而 expr 计算本身耗时长，造成 rule 评估堆积甚至阻塞
- 在多集群联邦场景中，把未加租户/集群标识的通用规则直接复用，导致指标混杂、无法归属
