kibana-alerting-rules

Kibana 告警规则

创建、检查、更新和管理 Kibana 告警规则：选择合适的规则类型，明确编码阈值和分组语义，仅在用户要求时附加操作；当用户想了解现有覆盖情况时，以只读方式列出或筛选规则。

环境配置

此技能通过 elastic CLI 执行 Elasticsearch 操作。如果未安装 elastic CLI，请告知用户其用途。不要猜测凭据、直接调用 HTTP API，也不要尝试其他变通方法。

此技能以 HTTP 简写形式引用操作（例如，GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）。本文末尾的 操作 表 列出了每种简写对应的 elastic CLI 命令 — 始终使用 CLI，而不是直接调用 HTTP API。

核心概念

规则由三个部分组成：条件（params + rule_type_id）、计划（检查条件的频率）和 操作（触发告警时运行的可选连接器）。满足条件时，规则会创建告警；操作通过连接器发送通知。除非用户明确要求配置通知，否则不要创建连接器或操作 — 许多任务只需要定义规则。

所需权限：拥有 Kibana 所属功能（Stack Rules、Observability、Security 等）上的 all 权限，以及 Rules Settings 上的 all 权限。管理连接器需要 Actions 和 Connectors 上的 all 权限；将现有连接器附加为规则操作只需 read 权限。

本地部署的前提条件： 创建规则前，请在 kibana.yml 中配置稳定的 xpack.encryptedSavedObjects.encryptionKey — 此密钥用于加密规则 API 密钥和连接器机密。如果未设置，密钥会在每次重启时重新生成，导致现有规则失效；集群中的所有 Kibana 节点必须使用相同的密钥。

流程

1. 确定任务类型。 判断用户需要创建规则、查找/列出规则（只读）、更新现有规则，还是进行生命周期变更（启用、禁用、静音、稍后提醒、删除）。如果用户只要求显示或列出规则，则按只读请求处理 — 不要创建、更新、启用或删除任何内容。

2. 对于查找/列出任务，合理筛选和分页。 调用 GET kbn:/api/alerting/rules/_find，并使用查询参数缩小结果范围，而不是一次性输出所有规则：

   • 按标签： filter=alert.attributes.tags:"production"（对 saved-object 属性使用 KQL）。
   • 按文本： 根据需要使用 search、search_fields 和 default_search_operator。
   • 分页： 如果结果可能超过一页，请设置 per_page 并遍历 page。
   • 排序： 使用 sort_field=name 和 sort_order=asc，确保列表稳定。

   列出匹配规则的 ID 和名称。如果没有规则匹配，请如实说明 — 不要捏造结果。只查询告警规则，不要查询连接器或数据流。

3. 对于创建任务，先选择规则类型，再编写参数。 将用户意图匹配到指标/阈值规则类型 — 不要选择日志、异常检测或无关类型：

   • 在时间窗口内统计数值指标，可选按主机/服务分组 → .index-threshold，并使用 consumer: "stackAlerts"。
   • 文档计数或 Query DSL 条件 → .es-query，并使用 consumer: "stackAlerts"。
   • metrics 应用中的 Observability 指标 → metrics.alert.threshold，并使用 consumer: "metrics" 或 "infrastructure"。

   请阅读 rule-types-reference.md，了解参数架构、有效的使用者和操作组。当用户指定索引、字段、阈值、持续时间和分组字段时，请在 params 中明确编码这四项 — 不要用连接器或操作代替条件。

4. 正确设置阈值、持续时间和分组。 这三个维度彼此独立：

   • 阈值： 在聚合值上设置 threshold 和 thresholdComparator。匹配字段的数值范围——ECS system.cpu.total.pct 通常是小数（90% 对应 0.9）；仅当字段采用 0–100 的数值范围时才使用 90。
   • “持续 N 分钟”的语义： 在 params 中设置 timeWindowSize 和 timeWindowUnit（每次运行时评估回溯窗口）。 让 schedule.interval 与该窗口一致（例如，两者都设为五分钟），避免短暂峰值因触发周期不匹配而触发告警。 仅当用户需要连续 N 次匹配运行，而非单个回溯窗口时，才添加 alert_delay: {"active": N}。
   • 按主机／实体分组： 对于 .index-threshold，将 groupBy 设为 "top"，将 termField 设为分组字段 （例如 host.name），并将 termSize 设得足够大，以涵盖所有实体（“任意主机”）。如果不分组，规则会进行全局聚合，不会按主机触发告警。

5. 构建创建请求载荷。 必填字段：name、rule_type_id、consumer、schedule、params。可选字段： tags、enabled、actions、alert_delay、flapping。如果用户提供了规则 ID，则在 URL 中使用该 ID； 否则由 Kibana 生成 ID。

   示例 params — 在 eval-alert-metrics 上检测任意主机的 CPU > 90%，持续 5 分钟：

   {
     "name": "CPU exceeds 90% for 5 minutes",
     "rule_type_id": ".index-threshold",
     "consumer": "stackAlerts",
     "schedule": { "interval": "5m" },
     "params": {
       "index": ["eval-alert-metrics"],
       "timeField": "@timestamp",
       "aggType": "avg",
       "aggField": "system.cpu.total.pct",
       "groupBy": "top",
       "termField": "host.name",
       "termSize": 1000,
       "threshold": [0.9],
       "thresholdComparator": ">",
       "timeWindowSize": 5,
       "timeWindowUnit": "m"
     },
     "tags": ["production"]
   }
   

   如果用户只要求创建规则条件，则省略 actions。

6. 创建并确认。 使用请求载荷调用 POST kbn:/api/alerting/rule/{id}。如果返回 409 Conflict，说明该 ID 已存在——调用 GET kbn:/api/alerting/rule/{id} 进行检查，或选择其他 ID。创建成功后，调用 GET kbn:/api/alerting/rule/{id}，并向用户确认实际规则 ID、名称和启用状态——未经 Kibana 验证，不要声称创建成功。

7. 更新任务：先读取，再替换。 rule_type_id 和 consumer 不可更改。调用 GET kbn:/api/alerting/rule/{id}，合并需要的更改，然后使用完整规则正文调用 PUT kbn:/api/alerting/rule/{id}。如果返回 409 Conflict，说明其他用户修改了规则——重新获取后重试。为每个操作设置 frequency 对象；规则级别的 notify_when 和 throttle 已弃用。

8. 生命周期任务：调用最具体的端点。 使用 POST kbn:/api/alerting/rule/{id}/_disable 临时禁用（规则配置会保留）；使用 POST kbn:/api/alerting/rule/{id}/_enable 重新启用。使用 POST kbn:/api/alerting/rule/{id}/_mute_all 静音所有告警；使用 POST kbn:/api/alerting/rule/{id}/_unmute_all 恢复。使用 POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute 静音单个活动告警；使用 POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute 取消静音。使用 POST kbn:/api/alerting/rule/{id}/snooze_schedule 安排暂停；使用 DELETE kbn:/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId} 移除暂停安排。使用 DELETE kbn:/api/alerting/rule/{id} 永久删除。如果规则因 API key 所有权问题而失败，则调用 POST kbn:/api/alerting/rule/{id}/_update_api_key。

示例

创建阈值告警

用户：“当任意主机的 CPU 超过 90% 并持续 5 分钟时提醒我。查询 eval-alert-metrics（system.cpu.total.pct， 按 host.name 分组）。创建 ID 为 eval-cpu-rule 的规则。”

1. 选择 .index-threshold / stackAlerts。
2. 将阈值设为小数 [0.9]，设置五分钟的 timeWindowSize／timeWindowUnit，并设置 groupBy／termField，以 host.name 分组。
3. 使用 schedule.interval: "5m" 调用 POST kbn:/api/alerting/rule/eval-cpu-rule。省略 actions。
4. 调用 GET kbn:/api/alerting/rule/eval-cpu-rule 并向用户确认。

按标签查找规则（只读）

用户：“显示所有生产告警规则。”

1. 使用 GET kbn:/api/alerting/rules/_find，设置 filter=alert.attributes.tags:"production"、合适的 per_page 和 sort_field=name。
2. 如果 total 超过 per_page，则翻页获取结果。
3. 仅报告 ID 和名称，不进行任何更改。

暂时暂停规则

用户：“停用规则 abc123，直到下周一。”

1. POST kbn:/api/alerting/rule/abc123/_disable。
2. 之后使用 POST kbn:/api/alerting/rule/abc123/_enable 重新启用。

对于跨越多条规则的计划停机时间，优先使用维护窗口，而不是逐条停用或暂停规则。

指南

• 在每个操作对象中设置 frequency；规则级别的 notify_when 和 throttle 已弃用。
• 创建后，rule_type_id 和 consumer 不可更改；如需更改，请删除并重新创建。
• 对于非默认 Kibana Spaces，请在路径前添加 kbn:/s/<space_id>/api/alerting/（连接器也按 Space 区分）。
• 规则操作不能引用其他 Space 中的连接器；规则及其连接器必须属于同一个 Space。
• 对于 PagerDuty、Jira 和 ServiceNow，请为活动通知操作配对添加 Recovered 操作。
• 使用 alert_delay 要求连续匹配；使用抖动设置抑制不稳定的告警。自 9.3 起，每条规则都可以通过 flapping 对象进行调优；更早版本仅支持 Space 级别的抖动设置。
• 在任意模板字段中使用 {{{.}}} 调试操作模板——它会将整个变量上下文渲染为 JSON，有助于找到 {{context.reason}} 或 {{alert.flapping}} 这样的正确路径。
• 不要将此技能用于 Security 检测规则：consumer: "securitySolution"/"siem" 属于专用的 Security Detections API（/api/detection_engine/rules），其规则类型 ID 和生命周期有所不同。
• 为规则统一添加标签（production、staging、团队名称），以便使用查找 API 进行筛选。
• 建议的最短检查间隔为 1m；开销较大的规则会在服务端运行超时后取消（默认值为 5m）。

常见问题

1. 规则类型错误——对指标阈值条件使用日志规则或 ML 规则。
2. 缺少按实体分组——用户要求“任意主机”或“每个服务”时却使用全局聚合。
3. 阈值比例不匹配——对小数形式的 CPU 字段使用 90 而不是 0.9。
4. 将持续时间与计划混为一谈——一分钟计划搭配五分钟窗口，与两者都设为五分钟的行为不同。
5. 添加未请求的操作——用户只要求创建规则，却附加了连接器。
6. 违反只读要求——用户只要求列出或筛选规则，却创建或更改了规则。
7. 并发更新冲突——未先获取最新数据就执行 PUT，会返回 409。
8. 导入/导出——保存对象导入会停用规则并移除连接器密钥。

参考资料

• rule-types-reference.md — 规则类型、参数、使用方、操作组
• connectors-actions-terraform.md — 操作、工作流、Terraform
• Kibana Alerting API
• 告警概念
• 规则操作变量
• 告警生产环境注意事项

操作

HTTP API (shorthand)	elastic CLI command
GET kbn:/api/alerting/rules/_find	elastic kb alerting get-alerting-rules-find [--filter '<kql>'] [--search '<q>'] [--per-page <n>] [--page <n>] [--sort-field <field>] [--sort-order asc|desc]
POST kbn:/api/alerting/rule/{id}	elastic kb alerting post-alerting-rule-id --id '<id>' --name '<name>' --rule-type-id '<type>' --consumer '<consumer>' --schedule '<json>' --params '<json>' [--tags '<json>'] [--actions '<json>'] [--enabled]
GET kbn:/api/alerting/rule/{id}	elastic kb alerting get-alerting-rule-id --id '<id>'
PUT kbn:/api/alerting/rule/{id}	elastic kb alerting put-alerting-rule-id --id '<id>' --name '<name>' --schedule '<json>' --params '<json>' [--tags '<json>'] [--actions '<json>']
DELETE kbn:/api/alerting/rule/{id}	elastic kb alerting delete-alerting-rule-id --id '<id>'
POST kbn:/api/alerting/rule/{id}/_enable	elastic kb alerting post-alerting-rule-id-enable --id '<id>'
POST kbn:/api/alerting/rule/{id}/_disable	elastic kb alerting post-alerting-rule-id-disable --id '<id>' [--untrack]
POST kbn:/api/alerting/rule/{id}/_mute_all	elastic kb alerting post-alerting-rule-id-mute-all --id '<id>'
POST kbn:/api/alerting/rule/{id}/_unmute_all	elastic kb alerting post-alerting-rule-id-unmute-all --id '<id>'
POST kbn:/api/alerting/rule/{id}/_update_api_key	elastic kb alerting post-alerting-rule-id-update-api-key --id '<id>'
POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute	elastic kb alerting post-alerting-rule-rule-id-alert-alert-id-mute --rule-id '<rule_id>' --alert-id '<alert_id>'
POST kbn:/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute	elastic kb alerting post-alerting-rule-rule-id-alert-alert-id-unmute --rule-id '<rule_id>' --alert-id '<alert_id>'
POST kbn:/api/alerting/rule/{id}/snooze_schedule	elastic kb alerting post-alerting-rule-id-snooze-schedule --id '<id>' --schedule '<json>'
DELETE kbn:/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}	elastic kb alerting delete-alerting-rule-ruleid-snooze-schedule-scheduleid --rule-id '<ruleId>' --schedule-id '<scheduleId>'