promtool test rules 是什么
promtool 是 Prometheus 官方自带的命令行工具，promtool test rules 用 YAML 描述「给定输入序列 → 期望的告警状态与查询结果」，在本地或 CI 中对告警规则、记录规则做单元测试。它不需要真实 Prometheus 实例，靠内置的评估引擎按指定间隔推演时间轴，因此非常适合作为规则变更的回归门禁：改阈值、改 for 时长、重写表达式之前先跑一遍用例。
基本信息
| 命令 | promtool test rules <测试文件或目录> |
|---|---|
| 输入 | 含 rule_files 与 tests 的 YAML |
| 断言块 | alert_rule_test、promql_expr_test |
| 版本要求 | 与线上 Prometheus 版本对齐 |
| 权限要求 | 普通用户，可读规则文件即可 |
典型使用场景
- CI 门禁：规则文件提交时自动执行，避免阈值误改造成漏报或狂报
- 重构验证：表达式等价改写后断言输出不变，确认语义没有被破坏
- 阈值调参：临时调整 input_series 模拟故障曲线，观察 for 时长对触发时刻的影响
- 变更评审：给评审者一份可执行用例，比贴 diff 更能说明行为变化
- 事故归档：把线上故障曲线固化成用例，防止同类问题再次上线
测试文件示例
测试文件示例
rule_files:
- alerts.yml
evaluation_interval: 1m
tests:
- interval: 1m
input_series:
- series: 'http_requests_total{job="api",code="500"}'
values: '0+10x30' # 初值 0，每分钟加 10，共 30 步
alert_rule_test:
- eval_time: 20m
alertname: ApiHighErrorRate
exp_alerts: [] # 该时刻预期尚未触发
- eval_time: 25m
alertname: ApiHighErrorRate
exp_alerts: # 预期触发，并逐字段核对标签与注解
- exp_labels:
severity: critical
exp_annotations:
summary: "错误率超过阈值"运行方式
运行方式
# 静态检查：规则语法与表达式是否合法
promtool check rules alerts.yml
# 执行断言（可传文件或目录）
promtool test rules tests/api_alerts_test.yml
# 流水线里建议先 check 再 test
promtool check rules alerts.yml && promtool test rules tests/测试文件关键字段
| 字段 | 作用 | 注意 |
|---|---|---|
| rule_files | 被测规则文件列表 | 路径相对测试文件所在目录 |
| evaluation_interval | 模拟的评估间隔 | 须与线上一致，否则 for 时长语义漂移 |
| input_series | 构造输入序列 | values 用 0+10x30 三段式简写 |
| alert_rule_test | 断言告警状态 | exp_alerts 为空数组表示预期不触发 |
| promql_expr_test | 断言查询结果 | 适合校验记录规则产出的聚合值 |
用例也要「预热」：eval_time 太早时 for 时长还没走完，规则一直停在 pending 而不触发，先在 for 时长上留足余量再设置断言时刻。