[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages

explore-analyze/alerting/experimental-alerting-system/rules.md

@@ -0,0 +1,35 @@
+---
+navigation_title: Rules
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+description: "Rules in Kibana's experimental alerting system define what to detect using ES|QL. Evaluation runs on a schedule and alerts, action policies, and notifications flow from rule detections."
+---
+
+# Rules in the {{alerting-v2-system}} [rules]
+
+A rule is where the {{alerting-v2-system}} starts. It points {{kib}} at the data you care about, describes what counts as a problem in {{esql}}, and says how often to check. Alerts, action policies, and notifications all flow from what a rule detects. 
+
+This page explains what rules do, what they don't control, and how to choose a creation path.
+
+## What rules do [detection-and-notification]
+
+On each run, a rule executes an {{esql}} query against your data. Matches are recorded as rule events (`rule_event`), and handled according to the rule's mode, which can be Signal mode or Alert mode. 
+
+In Signal mode, each matching row is stored as a signal document with no alert lifecycle or notifications. In Alert mode, the rule creates and tracks an alert episode for each match. Episodes move through lifecycle states, appear on the Alerts UI, and can trigger notifications through action policies.
+
+## What rules don't do 
+
+Rules only define *what* to detect. They don't control notifications, who gets notified, or when. That's the job of action policies, which are global objects scoped to your space that match alert episodes from any rule. A rule has no say in which action policies pick it up.
+
+This separation means you can build and test a rule without anyone getting paged, update notification routing without touching the rule, and have multiple action policies respond to the same rule independently.
+
+## Next steps
+
+- [Create a rule](rules/create-a-rule.md): Compare creation paths and choose the one that fits your workflow.
+- [Configure a rule](rules/configure-a-rule.md): Set the schedule, grouping, activation thresholds, recovery conditions, and no-data behavior.
+- [View and manage rules](rules/view-manage-rules.md): Enable, disable, clone, delete, and bulk-manage rules from the rules list.
+- [Review execution history](rules/review-rule-execution-history.md): Monitor rule and action policy execution outcomes across all rules in a space.
+- [{{esql}} query patterns](rules/esql-query-patterns.md): Browse query patterns ordered by complexity, from a basic event filter to SLO burn rate and persistent breach detection.

explore-analyze/alerting/experimental-alerting-system/rules/configure-a-rule.md

@@ -0,0 +1,24 @@
+---
+navigation_title: Configure a rule
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+description: "Overview of all configurable rule settings in the experimental alerting system. Required settings are mode, ES|QL query, and schedule. Optional settings include severity, grouping, activation and recovery thresholds, no-data handling, and tags."
+---
+
+# Configure a rule in the {{alerting-v2-system}} [rule-settings]
+
+Rules in the {{alerting-v2-system}} have three required settings and several optional ones. Start with the required settings in order. Only add optional settings once the detection logic is validated. The following table links to a dedicated page for each setting with field descriptions, accepted values, and guidance on when to configure it.
+
+| Setting | Description | Required |
+| --- | --- | --- |
+| [Rule mode](configure-rule-mode.md) | Can be Signal or Alert. Controls whether matching rows generate signal documents or tracked alert episodes. | Required |
+| [{{esql}} query](configure-rule-query.md) | The detection logic and the parameters available in query expressions. | Required |
+| [Schedule and lookback](configure-rule-schedule.md) | How often the rule evaluates and how far back the query looks. | Required |
+| [Severity](configure-rule-severity.md) | Assign severity levels to alert episodes using a `severity` column in query output. | Optional |
+| [Grouping](configure-rule-grouping.md) | Track multiple subjects (hosts, services, users) as independent alert series in one rule. | Optional |
+| [Activation and recovery thresholds](configure-rule-thresholds.md) | Reduce noise with delay modes for opening and closing alert episodes. Alert mode only. | Optional |
+| [No-data handling](configure-no-data-handling.md) | What the rule records when the base query returns no results. | Optional |
+| [Tags and runbooks](configure-rule-tags.md) | Free-form labels and investigation guides attached to the rule. Alert mode only. | Optional |

explore-analyze/alerting/experimental-alerting-system/rules/configure-no-data-handling.md

@@ -0,0 +1,55 @@
+---
+navigation_title: No-data handling
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+description: "How to configure the no-data strategy for rules in the experimental alerting system. Controls whether an empty query result emits a no-data event, holds the last known alert state, triggers recovery, or is ignored."
+---
+
+# No-data handling in the {{alerting-v2-system}} [no-data-handling]
+
+No-data handling is an optional setting for rules in the {{alerting-v2-system}}. Use `no_data_strategy` to control what the rule records when the base query returns no results. Setting this correctly prevents false recoveries and misleading `no_data` events when data sources stop reporting.
+
+## No-data strategy options [no-data-strategy-options]
+
+The `no_data_strategy` field accepts the following values.
+
+| Value | Description |
+| --- | --- |
+| `emit` | Record a no-data event. |
+| `last_known_status` | Hold the last known lifecycle state. An active breach stays active and a recovered episode stays recovered. |
+| `recover` | Treat absence as recovery. |
+| `none` | Turn off no-data detection |
+
+:::{note}
+`no_data_strategy` only applies when the base query returns **no rows at all**. If one host or data source goes silent while others continue reporting, the query still returns results for the active sources and `no_data_strategy` does not trigger. Refer to [No-data detection](esql-no-data-detection.md) for an {{esql}} pattern that surfaces individual silent sources as alert rows.
+:::
+
+## When to configure no-data handling [no-data-when-to-use]
+
+Configure `no_data_strategy` when:
+
+* The data source your rule monitors can go silent. Examples include a metrics agent that stops reporting, a pipeline that breaks, or a service that stops generating events.
+* A false recovery caused by an empty query result would be more harmful than holding the current alert state.
+* Absence of data is itself a signal worth surfacing, such as missing heartbeat events from a critical service.
+
+Leave `no_data_strategy` unconfigured (or set to `none`) when:
+
+* Your data source reliably produces output on every evaluation and a gap in data would indicate a genuine recovery.
+* You are still tuning the rule and don't yet know how it behaves when data is absent. Set the strategy once the rule's normal behavior is understood.
+
+## Examples
+
+### Maintain alert state during a metrics collection outage
+
+This rule monitors infrastructure CPU. If the metrics collection agent stops sending data, you don't want an active CPU breach to auto-recover because the query returned nothing. Set `no_data_strategy` to `last_known_status`. The rule holds the alert in its current state until data resumes.
+
+Use this when an empty query result most likely means a pipeline problem rather than a genuine recovery.
+
+### Surface a broken data pipeline as an alert
+
+This rule monitors for login events from an identity provider. If no events appear in the lookback window, it's unusual enough to warrant attention. Either the pipeline is broken or something has suppressed activity. Set `no_data_strategy` to `emit`. The absence is recorded as a `no_data` event in `.rule-events`, making it visible alongside other rule activity.
+
+Use this when receiving no data is itself a signal worth investigating.

explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-grouping.md

@@ -0,0 +1,68 @@
+---
+navigation_title: Grouping
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+description: "Configure rule grouping in Kibana's experimental alerting system to track multiple subjects as independent alert series."
+---
+
+# Rule grouping in the {{alerting-v2-system}} [rule-grouping]
+
+Rule grouping is an optional setting in the {{alerting-v2-system}} that lets a single rule track multiple things independently. For example, a rule monitoring CPU usage across hosts can produce a separate alert series for each host, rather than one alert for everything combined.
+
+In Alert mode, each group becomes its own alert episode with an independent lifecycle. One group can be active while another has recovered, and notifications apply per episode, not across all groups combined. Snooze state is also per series. Snoozing one group does not affect other groups tracked by the same rule.
+
+## When to configure grouping [grouping-when-to-use]
+
+Configure grouping when:
+
+* Your {{esql}} query uses a `BY` clause to aggregate across multiple subjects such as hosts, services, or users, and you want each subject to have an independent alert lifecycle.
+* You need to track that one host has recovered while another is still breaching, rather than treating all subjects as a single combined series.
+* You want action policy notifications to apply per subject rather than firing once for the entire rule.
+
+Skip grouping when:
+
+* Your query does not use a `BY` clause. Grouping requires `BY` columns in the query output to be meaningful.
+* You intentionally want a single alert series for the rule regardless of how many subjects match. An example is a rule that fires when any host in a cluster is down and the individual host identity doesn't matter for the notification.
+
+Rule grouping controls how alert series are created. Notification grouping, configured on an action policy, controls how those alert episodes are batched into messages. These are separate settings.
+
+## Configure grouping fields [grouping-fields-config]
+
+The {{alerting-v2-system}} does not automatically infer grouping from your {{esql}} query. When your query uses `BY` to produce one row per group, the system still treats all rows as a single series unless you explicitly declare which fields define series identity in the grouping configuration. The fields you declare in `grouping.fields` are what the system uses to separate rows into independent alert series and track each one through its own lifecycle.
+
+The fields you declare in `grouping.fields` must match the column names produced by the `BY` clause in your {{esql}} `STATS` command. If they don't match, the system can't correlate query rows to alert series and the grouping configuration has no effect.
+
+:::{tip}
+Write the query first, then set the group fields. That way the `BY` columns are already defined and you can select them directly. If you later add or remove a `BY` field in the query, update the group fields to match.
+:::
+
+## Examples
+
+### Track error rates per service
+
+This rule counts HTTP errors per service and opens a separate alert series for each service that exceeds the threshold. Each service gets its own lifecycle. If the checkout service recovers but the payments service stays critical, those are tracked independently.
+
+```esql
+FROM logs-*
+| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend
+| STATS error_count = COUNT_IF(http.response.status_code >= 500) BY service.name  // Group field: one series per service
+| WHERE error_count > 10
+| KEEP service.name, error_count
+```
+
+Without a matching `grouping.fields` entry, the rule treats all services as a single combined series. A spike in one service would activate the alert for everything, and recovery requires all services to drop below the threshold at the same time.
+
+### Track CPU usage per host and region
+
+When the query groups by multiple fields, include all fields in `grouping.fields` to create one alert series per unique combination.
+
+```esql
+FROM metrics-*
+| WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend
+| STATS avg_cpu = AVG(system.cpu.total.pct) BY host.name, cloud.region  // Group fields: one series per host+region pair
+| WHERE avg_cpu > 0.90
+| KEEP host.name, cloud.region, avg_cpu
+```

explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-mode.md

@@ -0,0 +1,50 @@
+---
+navigation_title: Rule mode
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+description: "How rule mode determines whether detections produce signal documents or tracked alert episodes in the experimental alerting system, and when to use each."
+---
+
+# Rule mode in the {{alerting-v2-system}} [rule-mode]
+
+Rule mode is a required setting for rules in the {{alerting-v2-system}}. It determines what the rule produces when the detection query finds a match. Rule mode is set by the rule creation method. Some [creation paths](create-a-rule.md) only support one mode.
+
+| Mode | Behavior |
+| --- | --- |
+| Signal | Records each matching row as a signal document. No alert episodes, no notifications. |
+| Alert | Creates an alert episode for each matching row. Episodes are tracked through lifecycle states, appear on the Alerts UI, and can be routed to notifications by action policies. |
+
+## When to use each rule mode [rule-mode-when-to-use]
+
+Signal mode is the right fit when:
+
+* You are writing a new detection query and want to verify it produces the expected matches before notifying anyone.
+* You need to build detection history in `.rule-events` without generating alert noise or triggering notifications.
+
+Signal mode is **not** the right fit when:
+
+* You need to track how long a condition has been active or how it transitions between states. Signal mode does not create episodes or lifecycle state.
+* You need notifications when a condition fires. Switch to Alert mode and attach an action policy.
+
+Alert mode is the right fit when:
+
+* The rule is production-ready and each breach should be tracked as a distinct alert episode that opens, can escalate, and closes when the condition clears.
+* Alert episodes from the rule should be available for be triage, acknowledgment, or escalation.
+* You want to attach action policies to route notifications when alert episodes open, escalate, or recover.
+
+Alert mode is **not** the right fit when:
+
+* The rule's query is still being tuned and generating alerts would create noise for on-call teams. Use Signal mode to validate first, then switch.
+
+## Examples
+
+### Build detection history before enabling alerts
+
+You're writing a new detection query and want to verify it produces the results you expect before anyone gets paged. Create the rule in Signal mode so matches are recorded in `.rule-events` and you can inspect them in Discover without opening any alert episodes or triggering notifications. Once the matches look correct, edit the rule and switch it to Alert mode.
+
+### Route critical episodes to an on-call workflow
+
+You have a checkout service error rate rule and want on-call engineers notified when it fires. Create the rule in Alert mode so each breach opens a tracked episode that action policies can route to a notification channel. The rule's episodes appear on the Alerts UI and are visible to any action policy whose KQL matcher matches the episode fields.