elastic · nastasha-solomon · May 15, 2026 · May 15, 2026 · May 27, 2026 · May 27, 2026
@@ -149,8 +149,8 @@ subs:
   ls-pipelines-app:   "Logstash Pipelines"
   maint-windows-app:   "Maintenance Windows"
   maint-windows-cap:   "Maintenance windows"
-  alerting-v2:   "experimental alerting features"
-  alerting-v2-cap:   "Experimental alerting features"
+  alerting-v2-system:   "experimental alerting system"
+  alerting-v2-system-cap:   "Experimental alerting system"
   custom-roles-app:   "Custom Roles"
   data-source:   "data view"
   data-sources:   "data views"

@@ -8,28 +8,55 @@ applies_to:
 products:
   - id: kibana
   - id: cloud-serverless
+  - id: elasticsearch
+  - id: cloud-hosted
+navigation_title: Alerting
+description: Watch your data and respond to conditions automatically with Elastic alerting. Compare Kibana alerting, the experimental ES|QL-based alerting system, and Watcher to find the right fit.
 ---
 
-# Alerting
+# Alerting [alerting-overview]
 
-Alerting tools in Elasticsearch and Kibana provide functionality to monitor data and notify you about significant changes or events in real time. This page provides an overview of how the key components work.
+Elastic alerting helps you watch your data and respond when something needs attention, whether that is a metric crossing a limit, an asset leaving an area on a map, or an unusual pattern in your time series. You set the conditions and how people should be notified. Elastic runs the checks for you.
 
-## Alerts
+Elastic offers three alerting systems. For most new projects and projects on the most recent {{kib}} versions, the {{alerting-v2-system}} is the recommended system. If you're not sure which fits your situation, refer to [Compare alerting systems](alerting/compare-alerting-systems.md).
 
-Alerts are notifications generated when specific conditions are met. These notifications are sent to you through channels that you previously set such as email, Slack, webhooks, PagerDuty, and so on. 
+## {{alerting-v2-system-cap}}
 
-Alerts are created based on rules, which define the criteria for triggering them. Rules monitor the data indexed in Elasticsearch and evaluate conditions on a defined schedule to identify matches. For example, a threshold rule can generate an alert when a value crosses a specific threshold, while a machine learning rule activates an alert when an anomaly detection job identifies an anomaly.
+```{applies_to}
+stack: experimental 9.5+
+serverless: experimental
+```
+
+The {{alerting-v2-system}} is built on {{esql}}. You write the query that defines what to watch for, choose how alert episodes are tracked per series, and control notifications through action policies that handle routing, frequency, and notification batching. The {{alerting-v2-system}} also adds alert episode lifecycle tracking, per-series snooze, and rules on alert episodes for correlation and escalation. It is a strong fit when you want full control over what data travels with each alert episode and how your team is notified.
+
+:::{note}
+The {{alerting-v2-system}} runs next to {{kib}} alerting on {{serverless-full}} and {{stack}} 9.5 and later. You don't have to move everything at once. You can copy or rebuild rules when you're ready, and your existing {{kib}} alerting rules won't be affected.
+:::
+
+[Get started with the {{alerting-v2-system}} →](alerting/kibana-alerting-experimental.md)
+
+## {{kib}} alerting
+
+```{applies_to}
+stack: ga
+serverless: ga
+```
+
+{{kib}} alerting gives you ready-made rule types that work with applications such as APM, metrics, security, and uptime monitoring. You set conditions on a schedule you choose and send notifications through common channels (email, chat apps, webhooks, on-call tools, and more). Setup uses forms and clear steps, so you do not need to learn a query language first. It is a strong fit when you want broad coverage out of the box.
+
+[Get started with {{kib}} alerting →](alerting/alerts.md)
 
 ## Watcher
+
 ```{applies_to}
+stack: ga
 serverless: unavailable
 ```
 
-You can use Watcher for alerting and monitoring specific conditions in your data. It enables you to define rules and take automated actions when certain criteria are met. Watcher is a powerful alerting tool for custom use cases and more complex alerting logic. It allows advanced scripting using Painless to define complex conditions and transformations.
+Watcher is for unusual or highly tailored setups where you need scripts, chained steps, or close control over {{es}} APIs. It does not use the main {{kib}} rules UI used by {{kib}} alerting. It is available on the {{stack}} only, not in {{serverless-full}}.
 
 :::{tip}
-For most use cases, you should use Kibana Alerts instead of Watcher. Kibana Alerts allows rich integrations across use cases like APM, metrics, security, and uptime. Prepackaged rule types simplify setup and hide the details of complex, domain-specific detections, while providing a consistent interface across Kibana.
-
-Watcher is not available in {{serverless-full}}.
+For most teams, {{kib}} alerting or the {{alerting-v2-system}} is easier to adopt than Watcher. Both work within {{kib}}'s rules UI and don't require writing {{es}} watch definitions.
 :::
 
+[Get started with Watcher →](alerting/watcher.md)
@@ -16,9 +16,15 @@
 # {{kib}} alerting [alerts]
 
 {{kib}} alerting is the built-in alerting system in {{kib}}. It lets you define rules that check your data on a schedule, create alerts when conditions are met, and trigger actions through connectors (email, Slack, webhooks, and more). It is available on all deployments.
-<!-- TODO: Uncomment when PR #6521 (experimental overview) is merged:
-For the {{alerting-v2}} built on {{esql}}, refer to [{{alerting-v2-cap}}](kibana-alerting-experimental.md).
--->
+
+:::{note}
+:applies_to: {"stack": "experimental 9.5+", "serverless": "experimental"}
+For the {{alerting-v2-system}} built on {{esql}}, refer to [{{alerting-v2-system-cap}}](kibana-alerting-experimental.md).
+:::
+
+::::{note}
+In this doc, *alert* refers to a tracked occurrence of a rule condition. If you're using the {{alerting-v2-system}}, the equivalent concept is called an *alert episode*. The two terms describe similar ideas in different systems and are not interchangeable.
+::::
 
 ## {{rules-ui}} [rules]
 

@@ -0,0 +1,53 @@
+---
+navigation_title: Compare alerting systems
+applies_to:
+  stack: ga
+  serverless: ga
+products:
+  - id: kibana
+  - id: cloud-serverless
+  - id: elasticsearch
+  - id: cloud-hosted
+description: Compare Kibana alerting, the experimental ES|QL-based alerting system, and Watcher by use case and deployment type to select the right tool for your monitoring needs.
+---
+
+# Compare alerting systems [compare-alerting-systems]
+
+Elastic offers three alerting systems, each suited to different use cases and workflows. For most new projects and projects on the most recent {{kib}} versions, the {{alerting-v2-system}} is the recommended system. Use this page to compare them by goal, feature, and availability.
+
+## Select by use case
+
+| Goal | Suggested system | Availability |
+|---|---|---|
+| Monitor metrics, logs, or uptime with ready-made rules and no query language | [{{kib}} alerting](alerts.md) | {applies_to}`stack: ga` {applies_to}`serverless: ga` |
+| Use rules built for {{elastic-sec}}, {{observability}}, APM, or Maps | [{{kib}} alerting](alerts.md) | {applies_to}`stack: ga` {applies_to}`serverless: ga` |
+| Write {{esql}} to define exactly what to detect and what data each alert episode carries | [{{alerting-v2-system-cap}}](kibana-alerting-experimental.md) | {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.5+` |
+| Query alert history in Discover or build dashboards from alert data | [{{alerting-v2-system-cap}}](kibana-alerting-experimental.md) | {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.5+` |
+| Manage notification routing, grouping, and throttling in one place, reusable across rules | [{{alerting-v2-system-cap}}](kibana-alerting-experimental.md) | {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.5+` |
+| Build highly custom notification logic with reusable, configurable workflows | [{{alerting-v2-system-cap}}](kibana-alerting-experimental.md) | {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.5+` |
+| Build highly custom logic with scripting and chained inputs | [Watcher](watcher.md) | {applies_to}`stack: ga` {applies_to}`serverless: unavailable` |
+
+## Compare at a glance
+
+| | {{kib}} alerting | {{alerting-v2-system-cap}} | Watcher |
+|---|---|---|---|
+| **Best for** | Teams using built-in rule types with form-based setup | Teams that need full control over detection and notification routing | Custom alerting logic requiring scripting |
+| **Rule definition** | Select a rule type and fill in parameters | Write an {{esql}} query or use a rule builder with form-based setup | Write a JSON watch definition |
+| **Alert data** | In-place updates, limited query support | Append-only events queryable with {{esql}} in Discover | Watch history index |
+| **Notifications** | Configured per action on each rule | Centralized action policies, reusable across rules; supports action-level throttling and conditions | Action-level throttling and conditions |
+| **Noise reduction** | Snooze per rule, maintenance windows | Per-episode acknowledge or deactivate, per-series snooze, maintenance windows, match condition routing in action policies | Action conditions and throttling |
+| **Available on {{serverless-full}}** | Yes | Yes, {applies_to}`serverless: experimental` | No |
+| **Available on {{stack}}** | Yes | Yes, {applies_to}`stack: experimental 9.5+` | Yes |
+
+<!--
+TODO: Once PRs #6523, #6525, and #6527 are merged, add cross-links to the experimental system cells in the comparison table above. The cells currently describe the system but don't link anywhere. Suggested targets:
+
+| Row                        | Link target                                                                 |
+|----------------------------|-----------------------------------------------------------------------------|
+| Alert data (experimental)  | kibana-alerting-experimental/alerts/query-alerts-and-signals-in-discover.md (PR #6527) |
+| Notifications (experimental) | kibana-alerting-experimental/notifications-actions.md or action-policies/about-action-policies.md (PR #6525) |
+| Noise reduction (experimental) | kibana-alerting-experimental/action-policies/reduce-notification-noise.md (PR #6525) |
+| Rule definition (experimental) | kibana-alerting-experimental/rules/configure-rule-query.md (PR #6523) |
+
+Also add links to the experimental system rows in the "Select by use case" table once the relevant pages are available.
+-->
@@ -0,0 +1,88 @@
+---
+navigation_title: Experimental alerting system
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+  - id: cloud-serverless
+description: The experimental Kibana alerting system uses ES|QL rules to detect conditions, track problems as alert episodes, and route notifications through reusable action policies.
+---
+
+# {{alerting-v2-system-cap}} overview [alerting-overview]
+
+The {{alerting-v2-system}} in {{kib}} watches your {{es}} data continuously, so your team doesn't have to. You define the conditions that matter, such as when to open an issue, who should know, and how often to notify them. The system handles the rest.
+
+::::{note}
+In the generally available {{kib}} alerting system, the term *alert* refers to a tracked occurrence of a rule condition. In the {{alerting-v2-system}}, the equivalent concept is called an *alert episode*. The two terms describe similar ideas in different systems and are not interchangeable.
+::::
+
+## The core idea [kibana-alerting-v2-overview]
+
+The {{alerting-v2-system}} separates *detecting* a problem from *acting* on it:
+
+- **Detecting** - Rules focus purely on what to watch for in your data and on collecting breach and recovery events.
+- **Acting** - Action policies handle who gets notified, when, and how, independently of any rule.
+
+You can build and test detection logic before wiring up any notifications, and update notification routing across all rules in one place without editing the rules themselves.
+
+## The four building blocks
+
+The {{alerting-v2-system}} is built around four objects: rules, alert episodes, action policies, and workflows, each with a distinct role.
+
+### Rules
+
+A rule defines what to watch for in your data and how often to check. Every rule runs in one of two modes: alert or signal.
+
+- **Alert** - Opens an alert episode when the rule finds a match and closes it when the condition clears, notifying your team at each episode state change. Helpful when you want to follow a problem from first detection to resolution.
+- **Signal** - Records rule query results over time without opening episodes or sending notifications. Helps you build a baseline, spot trends, or collect evidence before deciding whether something is worth alerting on.
+
+<!-- TODO: When PR #6523 (rules) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
+Refer to [Rules](kibana-alerting-experimental/rules.md) to learn more.
+-->
+
+### Alert episodes
+
+In Alert mode, the rule opens one alert episode per problem and keeps it open until the condition clears. The alert episode moves through states (pending, active, recovering, inactive) giving you one lifecycle to triage rather than a separate item per rule check.
+
+<!-- TODO: When PR #6527 (alerts) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
+Refer to [Alert episodes](kibana-alerting-experimental/alerts.md) to learn more.
+-->
+
+### Action policies
+
+An action policy is the gating layer between an alert episode and a workflow. It decides whether and when to invoke a workflow by evaluating suppression, match conditions, and frequency. Policy configuration determines the scope. A policy can apply to alert episodes from a specific rule, multiple rules, or all rules in the space.
+
+<!-- TODO: When PR #6525 (workflows/notifications) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
+Refer to [Notifications and actions](kibana-alerting-experimental/notifications-actions.md) to learn more.
+-->
+
+### Workflows
+
+A workflow is what actually sends the message or runs the automation, for example, posting to Slack, sending an email, calling a webhook. The {{alerting-v2-system}} invokes workflows through action policies that you configure to trigger on a schedule or on a state change on an alert episode.
+
+<!-- TODO: When PR #6525 (workflows/notifications) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
+Refer to [Connect workflows](kibana-alerting-experimental/workflows-alerting.md) to learn more.
+-->
+
+## How the pieces fit together [how-pieces-fit-together]
+
+At the simplest level:
+
+1. A rule checks your data on a schedule.
+2. The rule's query returns results when data matching its conditions is found.
+3. The rule's mode determines what happens next:
+   - **Alert** - The rule opens an alert episode to track the problem. An action policy can route it to a workflow to perform an action or send a notification.
+   - **Signal** - Each result is recorded for querying later. Nothing else happens.
+
+For a more detailed explanation of each stage, refer to [How the {{alerting-v2-system}} works](kibana-alerting-experimental/how-it-works.md).
+
+## Next steps
+
+<!-- TODO: When PRs #6523, #6525, and #6527 merge, replace the paragraph below with these three forward-facing tracks and remove the compare-alerting-systems link (it points here, not forward):
+- **Rules**: Refer to [Rules](kibana-alerting-experimental/rules.md) to learn how to create and configure detection rules.
+- **Alerts**: Refer to [Alerts](kibana-alerting-experimental/alerts.md) to learn how alert episodes work and how to triage them.
+- **Notifications**: Refer to [Notifications and actions](kibana-alerting-experimental/notifications-actions.md) to learn how action policies and workflows route notifications.
+-->
+
+To understand how the {{alerting-v2-system}} fits into {{kib}}'s alerting options, refer to [Alerting](../alerting.md) or [Compare alerting systems](compare-alerting-systems.md).
@@ -0,0 +1,71 @@
+---
+navigation_title: Glossary
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+  - id: cloud-serverless
+description: Definitions of key terms used throughout the experimental Kibana alerting system documentation.
+---
+
+# {{alerting-v2-system-cap}} glossary [alerting-v2-glossary]
+
+These terms appear throughout the {{alerting-v2-system}} docs. If a term is unclear while reading, check its definition here before going further.
+
+**Action policy**
+:   A configuration that controls whether and how often an alert episode triggers a notification, including which alerts qualify and how to avoid sending too many notifications. A single action policy can apply to one rule, several rules, or all rules in the space.
+<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
+    To learn more, refer to [Notifications and actions](notifications-actions.md).
+-->
+
+**Alert episode**
+:   The complete record of one problem tracked in Alert mode, from first detection to recovery, moving through states (pending, active, recovering, inactive).
+
+**Breach**
+:   A single instance when a rule's query finds a match, which may or may not open an alert episode depending on how the rule is configured.
+
+**Dispatcher**
+:   The background process that evaluates action policies against active alert episodes on a short interval (around 5 seconds), independent of the rule schedule.
+<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
+    To learn more, refer to [Reduce notification noise](action-policies/reduce-notification-noise.md).
+-->
+
+**{{esql}}**
+:   The query language every rule uses to search your data. To learn more, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql.md).
+
+**Notification**
+:   The message or action delivered when an alert episode matches an action policy and a workflow sends it, such as a Slack message, an email, or a webhook call.
+<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
+    To learn more, refer to [How action policies are evaluated](notifications-actions.md#how-action-policies-evaluated).
+-->
+
+**Rule**
+:   The definition of what to watch for in your data, how often to check, and what counts as a match; runs on a schedule and produces signals (Signal mode) or tracks alert episodes (Alert mode).
+<!-- TODO: Uncomment when PR #6523 (rules) is merged:
+    To learn more, refer to [Rules](rules.md).
+-->
+
+**Rule event**
+:   A record written to `.rule-events` every time a rule runs and its query finds a match; in Signal mode it is a signal, in Alert mode it belongs to an alert episode.
+
+**Severity**
+:   A label attached to alert episodes to indicate urgency; available as a filter in action policies so critical episodes can be routed differently from low-priority ones.
+<!-- TODO: Uncomment when PR #6523 (rules) is merged:
+    To learn more, refer to [Configure rule severity](rules/configure-rule-severity.md).
+-->
+
+**Signal**
+:   A rule event recorded in Signal mode; stored and queryable in Discover but doesn't open an alert episode or trigger notifications.
+
+**Threshold**
+:   The condition a rule uses to decide when something is worth alerting on, including how many times the condition must be met before an alert episode opens or closes.
+<!-- TODO: Uncomment when PR #6523 (rules) is merged:
+    To learn more, refer to [Activation and recovery thresholds](rules/configure-rule-thresholds.md).
+-->
+
+**Workflow**
+:   The automation that sends a message or runs an action when an action policy decides a notification should go out, such as posting to Slack, sending an email, or calling a webhook.
+<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
+    To learn more, refer to [Connect workflows](workflows-alerting.md).
+-->