3. 告警规则结构解析：Alerting Rule 的 YAML 结构、expr 表达式、for 持续时间、labels 与 annotations 设计

告警规则是 Prometheus 可观测性体系的“触发开关”。一个结构严谨的 Alerting Rule 不仅决定了告警是否准确，还直接影响后续的自愈剧本能否正确执行。本章将逐层拆解 Alerting Rule 的 YAML 骨架，深入分析 expr、for、labels 和 annotations 四个核心字段的设计原则与调优方法。

3.1 Alerting Rule 的完整 YAML 结构

一个标准的告警规则定义在 Prometheus 的 rules/*.yml 文件中，其顶层结构如下：

groups:
  - name: <group_name>                # 规则组名称，用于逻辑分组
    interval: <evaluation_interval>    # 该组规则的评估周期（可选，默认继承全局配置）
    rules:
      - alert: <alert_name>            # 告警名称，必须唯一
        expr: <promql_expression>      # PromQL 表达式，触发条件
        for: <duration>                # 持续时间，防止抖动
        labels:                         # 附加标签，用于路由与去重
          <key>: <value>
        annotations:                    # 注解，用于告警消息内容
          <key>: <value>

3.2 expr 表达式：告警触发的核心逻辑

expr 是 PromQL 表达式，它定义了“什么时候该告警”。表达式的结果必须是一个瞬时向量，且向量中的每个样本都代表一个潜在的告警实例。

3.3 for 持续时间：消除抖动与误告警

for 字段定义了告警条件必须持续满足多长时间后，告警状态才会从 Pending 转为 Firing。这是防止瞬时峰值或网络抖动引发无效告警的关键参数。

# 示例：CPU 高负载持续 5 分钟才触发告警
- alert: HighCpuUsage
  expr: node_cpu_seconds_total > 0.9
  for: 5m

调优建议：

• 基础设施类告警（如 CPU、内存）：推荐 for: 2m ~ 5m，避免毛刺。
• 业务类告警（如错误率、延迟）：推荐 for: 30s ~ 1m，快速响应。
• 自愈剧本联动：如果自愈动作需要快速介入，for 不宜过长，建议 ≤ 2m。

3.4 labels 设计：告警路由与去重标识

labels 是告警的元数据标签，用于告警分组、路由（如 Alertmanager 的 route 匹配）和去重。设计良好的 labels 能显著提升告警治理效率。

# 自愈场景下的 labels 设计示例
- alert: ApiHighErrorRate
  expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
  for: 1m
  labels:
    severity: critical
    team: sre
    service: api-gateway
    action: restart-pod

3.5 annotations 设计：告警消息的内容模板

annotations 用于携带告警的详细描述、当前值、建议操作等人类可读信息。这些内容会直接出现在告警通知（邮件、钉钉、Slack）中，是值班人员的第一手资料。

# 完整的 annotations 示例
annotations:
  summary: "{{ $labels.instance }} 错误率过高"
  description: "实例 {{ $labels.instance }} 在最近 5 分钟内的 5xx 错误率为 {{ $value | humanizePercentage }}，超过阈值 5%。"
  runbook_url: "https://runbook.team/api-error"
  auto_recovery: "true"

3.6 结构总览：从 YAML 到告警生命周期的映射

下面的 SVG 图展示了 Alerting Rule 各字段在告警生命周期中的位置与作用：

3.7 字段设计对比速查表

以下表格总结了四个核心字段的设计目标与调优方向，便于在自愈剧本开发时快速参考：