17.7.2 Prometheus告警规则语法与模板

Prometheus告警规则语法与模板#

告警规则通过 PromQL 表达式定义触发条件，结合 for、labels、annotations 形成可路由、可读、可操作的告警。规则文件以 YAML 编写，建议按业务组件拆分并用 promtool 校验，配合 Alertmanager 模板提升通知质量。

1. 原理草图：规则评估与告警生成链路#

2. 规则文件结构与字段（含完整示例）#

# /etc/prometheus/rules/node.yml
groups:
  - name: node.rules
    interval: 30s
    rules:
      - alert: NodeCPUHigh
        expr: 100 - (avg by(instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 85
        for: 5m
        labels:
          severity: critical
          service: node
          env: prod
          team: sre
        annotations:
          summary: "CPU使用率过高: {{ $labels.instance }}"
          description: "当前CPU使用率={{ printf \"%.2f\" $value }}%，阈值=85%，持续5分钟"
          runbook: "https://runbook.example.com/node/cpu"

说明：
- expr 返回向量即触发告警；for 避免短时抖动。
- labels 用于路由与分组；annotations 用于通知内容。

3. PromQL 触发条件设计（示例与解释）#

# /etc/prometheus/rules/service.yml
groups:
  - name: service.rules
    rules:
      - alert: Nginx5xxRateHigh
        expr: (sum by(instance) (rate(nginx_http_requests_total{status=~"5.."}[5m])) /
               sum by(instance) (rate(nginx_http_requests_total[5m]))) > 0.02
        for: 3m
        labels:
          severity: warning
          service: nginx
        annotations:
          summary: "Nginx 5xx比例过高: {{ $labels.instance }}"
          description: "5xx比例={{ printf \"%.4f\" $value }}，阈值=0.02"

解释：
- rate 计算 5 分钟速率；
- 通过 sum by(instance) 进行维度聚合；
- 比例告警适合衡量稳定性，而非绝对数。

4. 模板语法与常用变量（含渲染示例）#

annotations:
  summary: "{{ $labels.job }}: {{ $labels.instance }} 异常"
  description: |
    当前值={{ printf "%.2f" $value }}
    集群={{ $externalLabels.cluster }}
    指标={{ $labels.__name__ }}

渲染效果预期：
- summary 中会展示 job 与 instance；
- description 中会展示当前值与集群信息。

5. 安装与验证工具（promtool）#

# 以二进制包为例
wget https://github.com/prometheus/prometheus/releases/download/v2.49.1/prometheus-2.49.1.linux-amd64.tar.gz
tar -xf prometheus-2.49.1.linux-amd64.tar.gz
cd prometheus-2.49.1.linux-amd64
sudo cp promtool /usr/local/bin/

# 验证版本
promtool --version

6. 规则校验与表达式测试（命令与预期）#

# 语法校验
promtool check rules /etc/prometheus/rules/node.yml
# 预期输出：SUCCESS: 1 rules found

# 表达式测试（简化示例）
promtool test rules /etc/prometheus/tests/node.test.yml

# /etc/prometheus/tests/node.test.yml
rule_files:
  - /etc/prometheus/rules/node.yml
evaluation_interval: 30s
tests:
  - interval: 30s
    input_series:
      - series: 'node_cpu_seconds_total{instance="10.0.0.1:9100",mode="idle"}'
        values: '100 90 80 70 60 50 40 30 20 10'
    alert_rule_test:
      - eval_time: 5m
        alertname: NodeCPUHigh
        exp_alerts:
          - exp_labels:
              instance: "10.0.0.1:9100"
              severity: "critical"

7. 热加载规则与关键命令说明#

# 1) 通过 Web API 热加载
curl -X POST http://127.0.0.1:9090/-/reload

# 2) systemd 重启（不推荐频繁）
sudo systemctl restart prometheus

说明：
- /-/reload 需要 Prometheus 启动参数 --web.enable-lifecycle。

8. 排错清单（常见问题与处理）#

# 1) 规则未生效：检查配置加载
curl -s http://127.0.0.1:9090/api/v1/rules | jq '.data.groups[].name'

# 2) 表达式无数据：临时查询
curl -s "http://127.0.0.1:9090/api/v1/query?query=up" | jq '.data.result | length'

# 3) 语法错误定位
promtool check rules /etc/prometheus/rules/*.yml

排错要点：
- 规则文件路径是否在 prometheus.yml 的 rule_files 中；
- 指标名称和标签是否真实存在；
- for 时间过长导致 Pending 长期不触发。

9. 综合示例：采集中断与磁盘容量告警#

# /etc/prometheus/rules/misc.yml
groups:
  - name: misc.rules
    rules:
      - alert: ExporterDown
        expr: up == 0
        for: 2m
        labels:
          severity: critical
          category: system
        annotations:
          summary: "采集目标掉线: {{ $labels.instance }}"
          description: "job={{ $labels.job }} 连续2分钟无响应"

      - alert: DiskWillFillIn7Days
        expr: (node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} /
               node_filesystem_size_bytes{fstype!~"tmpfs|overlay"}) < 0.15
          and
               (predict_linear(node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"}[6h], 7*24*3600) < 0)
        for: 1h
        labels:
          severity: warning
          category: capacity
        annotations:
          summary: "磁盘容量7天内可能耗尽: {{ $labels.instance }}"
          description: "可用比例低于15%且趋势外推为负"

10. 练习题（含操作步骤）#

1) 练习：新增内存告警
- 目标：内存使用率 > 90% 持续 3 分钟
- 步骤：
- 新增 /etc/prometheus/rules/memory.yml
- 使用 promtool 校验
- 通过 /-/reload 使其生效

2) 练习：为告警模板添加 runbook
- 修改 NodeCPUHigh 的 annotations 增加 runbook
- 通过 api/v1/rules 验证规则已加载

3) 练习：验证告警触发
- 临时降低阈值（例如 1%）
- 在 Prometheus UI 中查看 Alerts 标签页是否 Firing
- 完成后恢复阈值并记录变化原因