/kibana-alerting-rules

name: kibana-alerting-rules
description: >
  Create and manage Kibana alerting rules. Use when creating, updating, or managing
  rule lifecycle (enable, disable, mute, snooze), choosing metric threshold rule types
  and params, or read-only find/list with tag filters.
metadata:
  author: elastic
  version: 0.3.0
  universal: true
compatibility: Kibana 8.x or 9.x with matching Elasticsearch, self-managed, Elastic
  Cloud Hosted, or Elastic Cloud Serverless; some rule types and features are version-
  or license-gated (for example, rule-level flapping is GA in 9.3). Requires the `elastic`
  CLI ≥ 0.2 with `stack kb` support.

Kibana Alerting Rules

Create, inspect, update, and manage Kibana alerting rules: choose the right rule type, encode threshold and grouping semantics, attach actions only when requested, and list or filter rules read-only when the user asks to discover existing coverage.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the [`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., `GET /`, `GET /_cat/indices`, `GET /{index}/_mapping`, `GET /{index}/_settings/index.mode`, `POST /_query`). The [Operations](#operations) table at the end of this document maps each shorthand to the equivalent `elastic` CLI command — always use the CLI rather than calling the HTTP API directly.

<!-- end-partial: preamble -->

Core concepts

A rule has three parts: **conditions** (`params` + `rule_type_id`), **schedule** (how often conditions are checked), and **actions** (optional connectors run when alerts fire). When conditions are met, the rule creates **alerts**; actions deliver notifications through **connectors**. Do not create connectors or actions unless the user explicitly asks for notification wiring — many tasks require only the rule definition.

Required privileges: `all` on the owning Kibana feature (Stack Rules, Observability, Security, etc.) and `all` on Rules Settings. Managing connectors needs `all` on Actions and Connectors; `read` is sufficient to attach existing connectors as rule actions.

**On-premises prerequisite:** configure a stable `xpack.encryptedSavedObjects.encryptionKey` in `kibana.yml` before creating rules — it encrypts rule API keys and connector secrets. If it is unset, each restart regenerates it and breaks existing rules; all Kibana nodes in a cluster must share the same key.

Process

1. **Classify the task.** Decide whether the user needs to **create** a rule, **find/list** rules (read-only), **update** an existing rule, or perform a **lifecycle** change (enable, disable, mute, snooze, delete). If the user only asks to show or list rules, treat the request as read-only — do not create, update, enable, or delete anything.

2. **For find/list tasks, filter and page sensibly.** Call `GET kbn:/api/alerting/rules/_find` with query parameters that narrow results instead of dumping every rule:

• **By tag:** `filter=alert.attributes.tags:"production"` (KQL on saved-object attributes).
• **By text:** `search` with `search_fields` and `default_search_operator` as needed.
• **Paging:** set `per_page` and iterate `page` when results may exceed one page.
• **Sort:** `sort_field=name` and `sort_order=asc` for stable listings.

Enumerate matching rule ids and names. If no rules match, say so plainly — do not invent results. Query alerting rules specifically, not connectors or streams.

3. **For create tasks, choose the rule type before writing params.** Match the user's intent to a metric/threshold rule type — not log, anomaly, or unrelated types:

• **Numeric metric over a time window, optionally per host/service** → `.index-threshold` with

`consumer: "stackAlerts"`.

• **Document count or Query DSL condition** → `.es-query` with `consumer: "stackAlerts"`.
• **Observability metric in the metrics app** → `metrics.alert.threshold` with `consumer: "metrics"` or

`"infrastructure"`.

Read [rule-types-reference.md](references/rule-types-reference.md) for param schemas, valid consumers, and action groups. When the user specifies an index, field, threshold, duration, and grouping field, encode all four explicitly in `params` — do not substitute a connector or action for the condition.

4. **Encode threshold, duration, and grouping correctly.** These three dimensions are independent:

• **Threshold:** set `threshold` and `thresholdComparator` on the aggregated value. Match field scale — ECS

`system.cpu.total.pct` is typically fractional (`0.9` for 90%); use `90` only when the field is on a 0–100 scale.

• **"For N minutes" semantics:** set `timeWindowSize` and `timeWindowUnit` in `params` (lookback evaluated each run).

Align `schedule.interval` with that window (e.g., both five minutes) so a brief spike does not fire on a mismatched cadence. Add `alert_delay: {"active": N}` only when the user wants N **consecutive** matching runs, not a single lookback window.

• **Per-host / per-entity grouping:** for `.index-threshold`, set `groupBy: "top"`, `termField` to the grouping field

(e.g., `host.name`), and a `termSize` large enough to cover all entities ("any host"). Without grouping, the rule aggregates globally and will not alert per host.

5. **Build the create payload.** Required fields: `name`, `rule_type_id`, `consumer`, `schedule`, `params`. Optional: `tags`, `enabled`, `actions`, `alert_delay`, `flapping`. Use the user-supplied rule id in the URL when given; otherwise let Kibana generate one.

**Example params — CPU > 90% on any host for 5 minutes on `eval-alert-metrics`:**

   {
     "name": "CPU exceeds 90% for 5 minutes",
     "rule_type_id": ".index-