3. 告警规则数据结构：核心字段解析

在服务目录的 Grafana 告警规则接口调用设计中，理解告警规则的数据结构是构建自动化管理能力的基础。Grafana 告警规则采用四层嵌套结构：Rule Group → Alert Rule → Condition → Data Source Query。每一层承载不同的职责，从规则的组织、触发条件的定义，到数据源的查询逻辑，层层递进。

3.1 四层结构总览

下面的 SVG 图展示了告警规则的四层嵌套关系，以及各层之间的包含与引用逻辑：

3.2 Rule Group（规则组）核心字段

Rule Group 是告警规则的顶层容器，对应 Grafana 中“文件夹”级别的组织单元。在 Prometheus 兼容模式下，一个 Rule Group 包含一组共享评估间隔的告警规则。

3.3 Alert Rule（告警规则）核心字段

Alert Rule 是告警规则的主体，定义了告警的元信息、触发条件引用、数据查询列表以及异常状态处理策略。

3.4 Condition（条件）核心字段

Condition 是告警规则的判定逻辑层，它不是一个独立的 API 对象，而是嵌入在 data[] 数组中的特殊查询类型（refId 被 condition 字段引用）。Condition 负责将多个数据源查询的结果进行组合、归约和阈值评估。

常见的 Condition 类型及其用途：

• classic_condition：经典条件，支持多查询组合，每个查询独立评估后通过 operator 组合
• reduce：归约操作，将时间序列数据归约为单个值（如取平均值）
• math：数学表达式，对多个查询结果进行算术运算
• threshold：阈值判定，将归约后的值与阈值进行比较
• resample：重采样，将不同时间粒度的数据对齐到统一时间窗口

3.5 Data Source Query（数据源查询）核心字段

Data Source Query 是告警规则的数据获取层，定义了从哪个数据源、使用什么查询语句、在什么时间范围内获取指标数据。一个告警规则可以包含多个数据源查询，通过 Condition 进行组合。

以 Prometheus 数据源为例，model 字段的典型结构：

{
  "refId": "A",
  "datasourceUid": "prometheus-uid-123",
  "queryType": "range",
  "model": {
    "expr": "avg(rate(http_requests_total{status=~"5.."}[5m]))",
    "intervalMs": 15000,
    "maxDataPoints": 100,
    "legendFormat": "5xx_rate"
  },
  "relativeTimeRange": {
    "from": 600,
    "to": 0
  }
}

3.6 完整请求体示例

以下是一个完整的创建告警规则 API 请求体，展示了四层结构的实际组合方式：

{
  "name": "生产环境-5xx告警组",
  "folderUID": "folder-abc-123",
  "interval": "1m",
  "rules": [
    {
      "title": "5xx错误率过高",
      "condition": "C",
      "noDataState": "NoData",
      "execErrState": "Error",
      "for": "5m",
      "annotations": {
        "summary": "5xx错误率超过阈值",
        "description": "当前5xx错误率 {{ $values.B }}%，阈值 5%"
      },
      "labels": {
        "severity": "critical",
        "team": "sre"
      },
      "data": [
        {
          "refId": "A",
          "datasourceUid": "prometheus-uid-123",
          "queryType": "range",
          "model": {
            "expr": "sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) * 100",
            "intervalMs": 15000,
            "maxDataPoints": 100
          },
          "relativeTimeRange": {
            "from": 600,
            "to": 0
          }
        },
        {
          "refId": "B",
          "queryType": "__expr__",
          "model": {
            "type": "reduce",
            "reducer": "last",
            "expression": "A"
          }
        },
        {
          "refId": "C",
          "queryType": "__expr__",
          "model": {
            "type": "threshold",
            "evaluator": {
              "type": "gt",
              "params": [5.0]
            },
            "expression": "B"
          }
        }
      ]
    }
  ]
}

3.7 字段校验规则速查

在服务目录的 API 调用中，字段校验失败是最常见的错误来源。下表总结了关键校验规则：