You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Summary
Preps the experimental alerting system overview page and related pages
for incoming content from PRs #6523 (rules), #6525 (notifications and
action policies), and #6527 (alerts). Changes follow the principle of
reducing duplication and orienting the overview page toward routing
readers forward rather than documenting the full system end-to-end.
## Changes
### `kibana-alerting-experimental.md`
**Glossary extracted to a dedicated page.** The glossary section (60+
lines) has been moved to `kibana-alerting-experimental/glossary.md` and
replaced with a two-line cross-reference. Keeping it on the overview
caused the page to function as both a conceptual introduction and a
reference, which made it harder to scan. The dedicated page allows the
overview to stay focused.
**"How the pieces fit together" section trimmed.** The six-step numbered
list in Alert mode and the three-step numbered list in Signal mode have
been replaced with 2–3 prose sentences each. The same content is
documented in `about-action-policies.md` (PR #6525); keeping a full
numbered flow on the overview created duplicate maintenance surface. The
diagrams and worked examples are retained.
**Examples made collapsible.** The Alert mode and Signal mode worked
examples are now wrapped in `::::{dropdown}` directives. This keeps the
examples available for readers who want them without making them a
required part of the overview flow.
**Terminology note added.** A callout clarifies that *alert* (classic
Kibana alerting) and *alert episode* (experimental system) describe
similar ideas in different systems and are not interchangeable. This
addresses terminology friction for readers who use both systems.
**"Four building blocks" sub-sections annotated for post-merge
trimming.** Each sub-section has a TODO comment identifying what to cut
and which child page to link to once the corresponding PR merges. The
content is unchanged for now since the child pages don't yet exist on
main.
**"Next steps" section prepped for post-merge replacement.** A TODO
comment in Next Steps contains the three forward-facing tracks (Rules,
Alerts, Notifications) ready to swap in once PRs #6523, #6525, and #6527
merge. Currently the section still points to the parent alerting page
and the choose-an-alerting-system page.
### `kibana-alerting-experimental/glossary.md` (new)
New page containing all glossary terms with 1-sentence definitions. TODO
comments are in place for each term's "To learn more" cross-link,
pointing to the correct child pages in the incoming PRs. Link paths are
relative to the glossary's location in the subdirectory.
### `alerts.md`
**Terminology note added.** A callout mirrors the one on the overview
page, telling readers that what this doc calls *alerts* are called
*alert episodes* in the experimental system. Placed after the existing
experimental system cross-reference callout.
### `choose-an-alerting-system.md`
**TODO comment added after the comparison table.** Documents which
comparison table cells should gain cross-links to child pages once PRs
#6523, #6525, and #6527 merge, with the specific target file for each
row.
### `toc.yml`
Added `glossary.md` as a child of `kibana-alerting-experimental.md`.
## Generative AI disclosure
1. Did you use a generative AI (GenAI) tool to assist in creating this
contribution?
- [x] Yes — Cursor + Claude
- [ ] No
Copy file name to clipboardExpand all lines: explore-analyze/alerting/alerts.md
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,9 +16,15 @@ description: "Overview of Kibana alerting: rules, alerts, actions, connectors, a
16
16
# {{kib}} alerting [alerts]
17
17
18
18
{{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.
19
-
<!-- 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).
21
-
-->
23
+
:::
24
+
25
+
::::{note}
26
+
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.
Copy file name to clipboardExpand all lines: explore-analyze/alerting/choose-an-alerting-system.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,3 +36,16 @@ Elastic has three alerting systems. You only need one. Pick the one that fits ho
36
36
|**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 |
37
37
|**Available on {{serverless-full}}**| Yes | Yes, {applies_to}`serverless: experimental`| No |
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:
The {{alerting-v2-system}} in {{kib}} is marked **Experimental** in the UI and is subject to change before general availability. It includes rules, alert episodes, action policies, workflows, and connectors. For the existing {{kib}} alerting system, refer to [{{kib}} alerting](alerts.md).
13
+
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.
14
14
15
-
The {{alerting-v2-system}} 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.
15
+
::::{note}
16
+
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.
17
+
::::
16
18
17
19
## The core idea [kibana-alerting-v2-overview]
18
20
@@ -29,31 +31,36 @@ A rule defines what to watch for in your data and how often to check. Every rule
29
31
-**Alert**: Opens an alert episode when the rule finds a match, keeps it open until the condition clears, and can notify your team or trigger automated actions when the state changes. Use this when you want the system to track an issue and tell someone about it.
30
32
-**Signal**: Records each match as a data point with no ongoing tracking and no notifications. Use this when you want to capture activity for later querying and investigation.
31
33
32
-
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
34
+
<!-- TODO: When PR #6523 (rules) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
33
35
Refer to [Rules](kibana-alerting-experimental/rules.md) to learn more.
34
36
-->
35
37
36
38
### Alert episodes
39
+
37
40
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. You manage alert episodes on the **Alerts** page.
38
-
<!-- TODO: Uncomment when PR #6524 (alerts) is merged:
41
+
42
+
<!-- TODO: When PR #6527 (alerts) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
39
43
Refer to [Alert episodes](kibana-alerting-experimental/alerts.md) to learn more.
40
44
-->
41
45
42
46
### Action policies
47
+
43
48
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. You can set conditions to filter which alert episodes it applies to, for example, only critical severity alert episodes from a specific service. Global action policies apply to alert episodes from any rule in the space. Per-rule action policies scope to a single rule for more targeted routing.
44
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
49
+
50
+
<!-- TODO: When PR #6525 (workflows/notifications) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
45
51
Refer to [Notifications and actions](kibana-alerting-experimental/notifications-actions.md) to learn more.
46
52
-->
47
53
48
54
### Workflows
49
-
A workflow is what actually sends the message or runs the automation, for example, posting to Slack or sending an email. Action policies hand off to workflows for delivery. Without a workflow attached, no notification is sent.
50
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
51
-
Refer to [Workflows for the {{alerting-v2-system}}](kibana-alerting-experimental/workflows-alerting.md) to learn more.
55
+
56
+
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 either through action policies (on a schedule, with conditions) or in direct response to a state change on an alert episode.
57
+
58
+
<!-- TODO: When PR #6525 (workflows/notifications) merges, uncomment the link below and trim this sub-section to 1–2 anchor sentences + the link.
59
+
Refer to [Connect workflows](kibana-alerting-experimental/workflows-alerting.md) to learn more.
52
60
-->
53
61
54
62
## How the pieces fit together [how-pieces-fit-together]
55
63
56
-
57
64
What happens after a rule finds something depends entirely on the rule's mode.
58
65
59
66
### Alert mode
@@ -68,111 +75,54 @@ Rule runs → the rule's conditions are met → writes a rule event
1. The rule evaluates {{esql}} on a schedule and writes a rule event to `.rule-events`.
72
-
2. The rule event opens or updates an alert episode, which is tracked until the condition resolves.
73
-
3. The dispatcher runs on a short interval, independently of the rule schedule, and picks up active alert episodes.
74
-
4. For each active alert episode, the dispatcher evaluates all enabled action policies. Each policy runs the episode through a sequence of gates: suppression, match conditions, and frequency.
75
-
5. For policies where the episode clears all gates, the dispatcher invokes the configured workflows.
76
-
6. Workflows deliver the notification or run the automation (email, chat, webhook, and so on).
78
+
The rule evaluates {{esql}} on a schedule and writes a rule event to `.rule-events`. When a match occurs, the dispatcher picks up the active alert episode, evaluates all enabled action policies against it, and invokes any workflows that pass suppression, match conditions, and frequency gates. When the condition clears, the episode recovers and recovery notifications fire through the same pipeline.
77
79
78
-
#### Example: Rule runs in Alert mode
80
+
::::{dropdown} Example: Rule runs in Alert mode
81
+
An SRE team wants to know when checkout service latency degrades, and notify the on-call team when it does. The team creates an Alert mode rule:
79
82
80
-
An SRE team creates a rule in Alert mode that checks checkout service latency every five minutes. When p95 exceeds 2 seconds for more than one consecutive check, the rule opens an alert episode. An action policy with a `rule.tags: "checkout"` matcher picks it up, skips low-severity alert episodes, and sends a Slack message through an on-call workflow.
83
+
1. The rule runs an {{esql}} query every five minutes, checking p95 checkout service latency.
84
+
2. When p95 exceeds 2 seconds for more than one consecutive check, the rule opens an alert episode.
85
+
3. An action policy with a `rule.tags: "checkout"` matcher skips low-severity episodes and sends a Slack message through an on-call workflow.
81
86
82
-
The on-call engineer gets one message, investigates, fixes a slow query, and latency drops. The alert episode recovers automatically. No dashboard watching required.
87
+
The engineer investigates, fixes a slow query, and the alert episode recovers automatically.
83
88
84
89
:::{image} ../images/rule-alert-mode-diagram.png
85
90
:alt: Diagram of Alert mode flow. A rule runs ES|QL on a schedule. When it finds a match, it writes a rule event tied to an ongoing alert episode. The alert episode moves through pending, active, recovering, and inactive states. An action policy matches eligible alert episodes and routes them to a workflow, which delivers a notification.
86
91
:::
92
+
::::
87
93
88
94
### Signal mode
89
95
90
-
Use Signal mode when you want to record matches for querying and analysis without alerting anyone. The rule writes a signal and stops. An alert episode is not opened, and notifications are not sent.
96
+
Use Signal mode when you want to record matches for querying and analysis without alerting anyone. The rule writes a signal and stops — no alert episode is opened and no notifications are sent.
91
97
92
98
```
93
99
Rule runs → the rule's conditions are met → writes a signal
94
100
→ queryable in Discover
95
101
→ no alert episode, no action policy, no notification
96
102
```
97
103
98
-
1. The rule evaluates {{esql}} on a schedule and writes a rule event (signal) to `.rule-events`.
99
-
2. The signal is available for querying in Discover, dashboards, and ES|QL.
100
-
3. No alert episode is opened. No action policy is evaluated. No notification is sent.
104
+
The rule evaluates {{esql}} on a schedule and writes a rule event (signal) to `.rule-events`. The signal is immediately available for querying in Discover, dashboards, and {{esql}}.
101
105
102
-
#### Example: Rule runs in Signal mode
106
+
::::{dropdown} Example: Rule runs in Signal mode
107
+
A security team wants to track calls to a rarely-used admin API endpoint, but individual calls aren't suspicious enough to page anyone. To start collecting data without generating noise, the team creates a Signal mode rule:
103
108
104
-
A security team wants to track when a rarely-used admin API endpoint is called. Individual calls are not inherently suspicious, so they do not want a notification every time the rule fires. The pattern only becomes meaningful in context. They create a rule in Signal mode that checks for requests to the endpoint every hour.
109
+
1. The rule runs an {{esql}} query on a schedule, checking for calls to the admin API endpoint.
110
+
2. Each time the condition is met, the rule writes a signal to `.rule-events`.
111
+
3. The signals accumulate silently and are immediately queryable in Discover.
105
112
106
-
The rule writes a signal each time it finds a match. No alert episodes are opened and no notifications go out.
113
+
After running the Signal mode rule for a few weeks, the team has enough data to understand normal call patterns and identify what volume looks anomalous. With that baseline established, the team is ready to create an Alert mode rule that opens an alert episode and notifies the on-call team when the call rate crosses a meaningful threshold.
107
114
108
115
:::{image} ../images/rule-detect-mode-diagram.png
109
116
:alt: Diagram of Signal mode flow. A rule runs ES|QL on a schedule. When it finds a match, it writes a signal to .rule-events. The signal is available for querying in Discover, dashboards, and ES|QL.
110
117
:::
118
+
::::
111
119
112
-
Later, an on-call alert fires for unusual privilege escalation on the same host. During the investigation, the team queries `.rule-events` in Discover and finds that the admin API endpoint was called three times in the hour before the escalation. The Signal mode rule events did not surface the incident. The Alert mode rule did. But without the signals already in the index, the admin API activity would have been invisible during the post-incident review.
These terms appear throughout the {{alerting-v2-system}} docs. If a term is unclear while reading, check its definition here before going further.
118
-
119
-
**Action policy**
120
-
: The gating layer between an alert episode and a workflow. You configure suppression rules, match conditions to filter which alert episodes it applies to, frequency settings to control batching and cooldown, and which workflow should send the message. Global action policies apply to alert episodes from any rule in the space. Per-rule action policies scope to a single rule.
121
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
122
-
To learn more, refer to [Notifications and actions](kibana-alerting-experimental/notifications-actions.md).
123
-
-->
124
-
125
-
**Alert episode**
126
-
: The complete record of one problem tracked in Alert mode, from when it was first detected to when it recovered. An alert episode moves through states (pending, active, recovering, inactive) as the situation changes. This is what you see and act on on the **Alerts** page.
127
-
128
-
**Breach**
129
-
: A single moment when a rule's query finds a match. One breach doesn't necessarily trigger a notification. You can configure a rule to require several consecutive breaches before it confirms the problem is real.
130
-
131
-
**Dispatcher**
132
-
: The background process in {{kib}} that runs the notification pipeline. On a short interval (around 5 seconds), it evaluates each enabled action policy against active alert episodes and sends notifications. The dispatcher runs on its own cadence, separate from the rule schedule.
133
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
134
-
To learn more, refer to [Reduce notification noise](kibana-alerting-experimental/action-policies/reduce-notification-noise.md).
135
-
-->
136
-
137
-
**{{esql}}**
138
-
: The query language every rule uses to search your data. To learn more, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql.md).
139
-
140
-
**Notification**
141
-
: The message or action delivered when an alert episode matches an action policy and a workflow sends it. Examples include a Slack message, an email, or a webhook call.
142
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
143
-
To learn more, refer to [How action policies are evaluated](kibana-alerting-experimental/notifications-actions.md#how-action-policies-evaluated).
144
-
-->
145
-
146
-
**Rule**
147
-
: The definition of what to watch for in your data, how often to check, and what counts as a problem. Rules run on a schedule. In Signal mode they produce signals. In Alert mode they track ongoing alert episodes.
148
-
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
149
-
To learn more, refer to [Rules](kibana-alerting-experimental/rules.md).
150
-
-->
151
-
152
-
**Rule event**
153
-
: A record written to `.rule-events` every time a rule runs and its query finds a match. Every rule produces rule events. In Signal mode the record is a signal. In Alert mode it belongs to an alert episode.
154
-
155
-
**Severity**
156
-
: A label you can attach to alert episodes to indicate how serious they are. Severity is available as a filter in action policies, so you can route critical alert episodes differently from low-priority ones.
157
-
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
158
-
To learn more, refer to [Author rules](kibana-alerting-experimental/rules/author-rules.md#severity-levels).
159
-
-->
160
-
161
-
**Signal**
162
-
: A rule event recorded when a rule runs in Signal mode. Signals are stored and queryable, but they don't open alert episodes or trigger notifications.
163
-
164
-
**Threshold**
165
-
: The condition a rule uses to decide when something is worth alerting on. This includes both the query that detects the problem and settings that control how many times the condition must be met before an alert episode opens or closes.
166
-
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
167
-
To learn more, refer to [Conditions and thresholds](kibana-alerting-experimental/rules/author-rules.md#conditions-and-thresholds).
168
-
-->
120
+
## Next steps
169
121
170
-
**Workflow**
171
-
: The automation that sends a message or runs an action when an action policy decides a notification should go out. Examples include posting to Slack, sending an email, or calling a webhook.
172
-
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
173
-
To learn more, refer to [Workflows for the {{alerting-v2-system}}](kibana-alerting-experimental/workflows-alerting.md).
122
+
<!-- TODO: When PRs #6523, #6525, and #6527 merge, replace the paragraph below with these three forward-facing tracks and remove the choose-an-alerting-system link (it points here, not forward):
123
+
- **Rules**: Refer to [Rules](kibana-alerting-experimental/rules.md) to learn how to create and configure detection rules.
124
+
- **Alerts**: Refer to [Alerts](kibana-alerting-experimental/alerts.md) to learn how alert episodes work and how to triage them.
125
+
- **Notifications**: Refer to [Notifications and actions](kibana-alerting-experimental/notifications-actions.md) to learn how action policies and workflows route notifications.
174
126
-->
175
127
176
-
## Next steps
177
-
178
-
To understand how the {{alerting-v2-system}} fits into {{kib}}'s alerting options, refer to [Alerting](../alerting.md) or [Choose an alerting system](choose-an-alerting-system.md).
128
+
To understand how the {{alerting-v2-system}} fits into {{kib}}'s alerting options, refer to [Alerting](../alerting.md) or [Choose an alerting system](choose-an-alerting-system.md).
0 commit comments