Prometheus 记录规则（Recording Rules）最佳实践（中文总结）

本文档来自 Prometheus 官方文档 - Recording Rules，重点在于如何为记录规则设计清晰、一致且可维护的命名方案，以提升可读性并避免逻辑错误。

一、记录规则命名规范

记录规则的名称应遵循以下通用格式：

1
level:metric:operations

各部分含义：

  • level：表示聚合级别，即输出指标中保留的标签维度。
    示例：instance_path、path、job
  • metric：原始指标名称，应保持不变，仅在使用 rate()/irate() 处理计数器时移除 _total 后缀。
    示例：requests（源自 requests_total）
  • operations：按从新到旧顺序列出对指标执行的操作。
    示例：rate5m、ratio_rate5m、mean5m

✅ 好处：一眼看出规则含义，错误计算会显得“格格不入”。

二、操作命名约定

场景 操作名 说明
使用 rate() 或 irate() rate5m、irate1m 等 包含时间窗口
多个相同结合律操作 合并（如 sum_sum → sum） 避免冗余
无明确操作 sum 默认聚合方式
两个指标相除（比率） A_per_B:ratio 如 request_failures_per_requests:ratio
Summary 的平均值（_sum / _count） mean 替代 ratio，更语义化

⚠️ 重要：计算比率时，必须先分别聚合分子和分母，再相除。
❌ 错误：avg(ratio)
✅ 正确：sum(numerator) / sum(denominator)

三、聚合与标签处理

  • 始终使用 without 子句显式指定要聚合掉的标签。
    例如：sum without (instance)(...)
  • 目的：
    • 保留如 job 等关键标签，避免冲突
    • 使输出指标更具上下文信息，便于告警和可视化
  • 输出指标的 level 必须与聚合后保留的标签一致。
    若不一致，很可能规则有误。

四、YAML 格式建议

为提高可读性，复杂表达式推荐使用 带缩进指示符的块引号（block scalar with indentation indicator）：

1
2
3
4
5
- record: path:request_latency_seconds:mean5m
  expr: |2
    sum without (instance)(instance_path:request_latency_seconds_sum:rate5m{job="myjob"})
    /
    sum without (instance)(instance_path:request_latency_seconds_count:rate5m{job="myjob"})
  • |2 表示内容整体缩进 2 个空格
  • 运算符（如 /）单独一行，提升可读性

五、典型示例

1. 聚合每秒请求数（按路径）

1
2
3
4
- record: instance_path:requests:rate5m
  expr: rate(requests_total{job="myjob"}[5m])
- record: path:requests:rate5m
  expr: sum without (instance)(instance_path:requests:rate5m{job="myjob"})

2. 计算失败率（并逐级聚合）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 先计算实例+路径级别的失败率
- record: instance_path:request_failures_per_requests:ratio_rate5m
  expr: |2
    instance_path:request_failures:rate5m{job="myjob"}
    /
    instance_path:requests:rate5m{job="myjob"}

# 聚合到路径级别
- record: path:request_failures_per_requests:ratio_rate5m
  expr: |2
    sum without (instance)(instance_path:request_failures:rate5m{job="myjob"})
    /
    sum without (instance)(instance_path:requests:rate5m{job="myjob"})

# 聚合到 job 级别
- record: job:request_failures_per_requests:ratio_rate5m
  expr: |2
    sum without (instance, path)(...)
    /
    sum without (instance, path)(...)

3. 计算平均延迟（来自 Summary）

1
2
3
4
5
6
7
8
9
10
11
- record: instance_path:request_latency_seconds:mean5m
  expr: |2
    instance_path:request_latency_seconds_sum:rate5m{job="myjob"}
    /
    instance_path:request_latency_seconds_count:rate5m{job="myjob"}

- record: path:request_latency_seconds:mean5m
  expr: |2
    sum without (instance)(...)
    /
    sum without (instance)(...)

六、关键原则总结

  • 命名即文档：规则名应自解释。
  • 保持 metric 不变：便于追踪原始指标。
  • 先聚合，再计算比率：确保统计正确性。
  • 显式声明聚合维度：用 without 避免意外。
  • 格式统一：提升团队协作效率。

📌 提示：此命名方案虽非强制，但被 Prometheus 社区广泛采用，强烈推荐遵循。