Skip to content

Commit 6d1db26

Browse files
nastasha-solomonclaude
nastasha-solomon
and
claude
committed
Add experimental alerting features setup pages
Adds three setup pages under kibana-alerting-experimental/: - quick-start-alerting.md: step-by-step first rule guide - setup-alerting.md: full setup covering data streams, spaces, and API keys - alerting-privileges.md: privilege requirements Cross-references to pages in later PRs are commented out with TODO notes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 8f8c4d0 commit 6d1db26

4 files changed

Lines changed: 270 additions & 0 deletions

File tree

‎explore-analyze/alerting/kibana-alerting-experimental/alerting-privileges.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
navigation_title: Privileges
3+
applies_to:
4+
stack: unavailable
5+
serverless: preview
6+
products:
7+
- id: kibana
8+
- id: cloud-serverless
9+
description: "Privilege requirements for the experimental alerting features: what {{kib}} feature access and {{es}} index access each role needs to manage rules, policies, alerts, and query alert data."
10+
---
11+
12+
# Experimental alerting features privileges [alerting-privileges]
13+
14+
15+
Privileges for the experimental alerting features control which users can manage rules, alerts, action policies, and query alert data. The experimental alerting features are part of Kibana and are marked **Experimental** in the UI.
16+
17+
<!--[CONTENT NEEDED: UI. The full privilege structure (names, granularity, and which actions each level permits) has not yet been finalized. Fill in the confirmed privilege requirements before publishing.]-->
18+
19+
## Manage rules [alerting-manage-rules-privileges]
20+
21+
[CONTENT NEEDED]
22+
23+
## Manage action policies [action-policy-management]
24+
25+
[CONTENT NEEDED]
26+
27+
## Manage alerts [alerting-manage-alerts-privileges]
28+
29+
[CONTENT NEEDED]
30+
31+
## Query alert data in Discover [alerting-discover-privileges]
32+
33+
[CONTENT NEEDED]

‎explore-analyze/alerting/kibana-alerting-experimental/quick-start-alerting.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
navigation_title: Quick start
3+
applies_to:
4+
stack: unavailable
5+
serverless: preview
6+
products:
7+
- id: kibana
8+
- id: cloud-serverless
9+
description: "Create your first rule in the experimental alerting features: enable the feature, write an {{esql}} query in the YAML editor, and confirm the rule is running by querying the rule events data stream."
10+
---
11+
12+
# Quick start: Your first rule [alerting-quick-start]
13+
14+
15+
This quick start is part of the experimental alerting features in Kibana. It walks you through the core model in action. You'll load sample error logs, create a rule that groups results by service, watch episodes open as the rule finds breaches, and then trigger recovery by deleting the data. By the end, you'll have learned about rules, grouping, episodes, and the alert lifecycle play out from start to finish.
16+
17+
## Step 1: Create a sample data stream
18+
19+
Run this in Dev Tools to create a data stream called `logs-tutorial` and populate it with sample error logs. This is the data your rule will query.
20+
21+
```json
22+
POST logs-tutorial/_bulk
23+
{ "index": {} }
24+
{ "@timestamp": "2026-04-21T21:50:00.000Z", "log_level": "ERROR", "service_name": "checkout", "message": "Connection timeout" }
25+
{ "index": {} }
26+
{ "@timestamp": "2026-04-21T21:51:00.000Z", "log_level": "ERROR", "service_name": "checkout", "message": "Database query failed" }
27+
{ "index": {} }
28+
{ "@timestamp": "2026-04-21T21:52:00.000Z", "log_level": "ERROR", "service_name": "checkout", "message": "Null pointer exception" }
29+
{ "index": {} }
30+
{ "@timestamp": "2026-04-21T21:50:00.000Z", "log_level": "ERROR", "service_name": "payments", "message": "Payment gateway unreachable" }
31+
{ "index": {} }
32+
{ "@timestamp": "2026-04-21T21:51:00.000Z", "log_level": "ERROR", "service_name": "payments", "message": "Transaction rollback failed" }
33+
{ "index": {} }
34+
{ "@timestamp": "2026-04-21T21:50:00.000Z", "log_level": "INFO", "service_name": "checkout", "message": "Request received" }
35+
{ "index": {} }
36+
{ "@timestamp": "2026-04-21T21:51:00.000Z", "log_level": "INFO", "service_name": "payments", "message": "Health check passed" }
37+
```
38+
39+
:::{note}
40+
`logs-tutorial` is automatically created as a data stream because the `logs-*` naming pattern matches Elasticsearch's default index template. You don't need to create it manually beforehand.
41+
:::
42+
43+
Confirm the data was indexed. You should see `errors: false` and `result: "created"` for each document in the response.
44+
45+
46+
## Step 2: Verify the data is queryable
47+
48+
Run this in Dev Tools to confirm the rule will find it:
49+
50+
```esql
51+
FROM logs-tutorial
52+
| WHERE log_level == "ERROR"
53+
| STATS error_count = COUNT() BY service_name
54+
| WHERE error_count >= 2
55+
```
56+
57+
You should see two rows: one for `checkout` (3 errors) and one for `payments` (2 errors). If you see this, the rule will trigger for both services.
58+
59+
## Step 3: Create the rule
60+
61+
Go to **Management > V2 Alerting Preview** and create a new rule using the YAML editor with the following configuration:
62+
63+
<!--[CONTENT NEEDED: UI. "V2 Alerting Preview" is a development-phase navigation label that will change. Update all instances of this navigation path in this tutorial before publishing.]
64+
-->
65+
66+
```yaml
67+
kind: alert
68+
metadata:
69+
name: tutorial-error-rate
70+
tags:
71+
- tutorial
72+
time_field: '@timestamp'
73+
schedule:
74+
every: 5s
75+
lookback: 24h
76+
evaluation:
77+
query:
78+
base: |-
79+
FROM logs-tutorial
80+
| WHERE log_level == "ERROR"
81+
| STATS error_count = COUNT() BY service_name
82+
| WHERE error_count >= 2
83+
grouping:
84+
fields:
85+
- service_name
86+
```
87+
88+
<!--[CONTENT NEEDED for M2: The `grouping` key will be renamed to `track_by` in M2. Update this example to use `track_by: { fields: [service_name] }` once that change ships.]
89+
-->
90+
91+
Save the rule. It will be enabled automatically.
92+
93+
94+
## Step 4: Confirm the rule is running
95+
96+
Wait 5 seconds, then run the following in Discover using the ES|QL mode. Replace `<your-rule-id>` with the `tutorial-error-rate` rule ID.
97+
98+
```esql
99+
FROM .rule-events
100+
| WHERE rule.id == "<your-rule-id>"
101+
| SORT @timestamp DESC
102+
| LIMIT 10
103+
```
104+
105+
:::{tip}
106+
After saving the rule, open its details page. The rule ID is the string at the end of the browser URL.
107+
:::
108+
109+
Check the following in the query results:
110+
111+
| Field | What you should see |
112+
|---|---|
113+
| `@timestamp` | Recent timestamps updating every 5 seconds |
114+
| `status` | `breached` confirms the query is finding matches |
115+
| `episode.status` | `active` confirms episodes have opened for both services |
116+
| `data.service_name` | `checkout` and `payments` confirms grouping is working |
117+
118+
119+
## Step 5: Confirm two episodes are open
120+
121+
In Discover, run:
122+
123+
```esql
124+
FROM .rule-events
125+
| WHERE rule.id == "<your-rule-id>"
126+
| STATS latest = MAX(@timestamp) BY episode.id, episode.status, data.service_name
127+
| SORT latest DESC
128+
```
129+
130+
You should see two rows: one episode for `checkout` and one for `payments`, both with `episode.status: active`.
131+
132+
133+
## Step 6: Trigger recovery
134+
135+
Delete the test data to clear the breach condition. Run the following in Dev Tools:
136+
137+
```json
138+
POST logs-tutorial/_delete_by_query
139+
{
140+
"query": { "match_all": {} }
141+
}
142+
```
143+
144+
Wait up to 5 seconds, then re-run the query from Step 5 in Discover. Both episodes should now show `episode.status: inactive`.
145+
146+
## What you learned
147+
148+
By completing this tutorial, you saw the core experimental alerting model in action end to end:
149+
150+
- **Rules query your data on a schedule.** Your rule ran every 5 seconds, checking for services with 2 or more errors in the last 24 hours.
151+
- **Grouping creates independent series.** Because the rule grouped by `service_name`, `checkout` and `payments` were tracked separately. Each got its own episode.
152+
- **Episodes follow a lifecycle.** When the error logs existed, both episodes moved to `active`. When you deleted the logs, both recovered and moved to `inactive` automatically, no manual intervention required.
153+
- **Rule events are the underlying record.** Every evaluation wrote documents to `.rule-events`, giving you a full queryable history of what the rule found and when.
154+
155+
## Next steps
156+
157+
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
158+
- **Add notifications:** Create a workflow and action policy to route alerts when an episode opens or recovers. Refer to [Notifications](notifications.md).
159+
-->
160+
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
161+
- **Use your own data:** Swap `logs-tutorial` for a real data source and update the breach condition to match your use case. Refer to [Author rules](rules/author-rules.md) to learn more.
162+
-->
163+
<!-- TODO: Uncomment when PR #6524 (alerts) is merged:
164+
- **Explore rule history in Discover:** Query `.rule-events` to track trends, compare episode durations, and identify which services breach most frequently. Refer to [Query alerts and signals in Discover](alerts/query-alerts-and-signals-in-discover.md) to learn more.
165+
-->

‎explore-analyze/alerting/kibana-alerting-experimental/setup-alerting.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
navigation_title: Set up
3+
applies_to:
4+
stack: unavailable
5+
serverless: preview
6+
products:
7+
- id: kibana
8+
- id: cloud-serverless
9+
description: "Get the experimental alerting features running in your space: enable the UI, confirm data streams, then understand spaces, API keys, and privileges."
10+
---
11+
12+
# Set up the experimental alerting features [alerting-setup]
13+
14+
15+
Set up is part of the experimental alerting features in Kibana. Before you can create your first rule, the experimental alerting features need to be enabled in your space and a few background systems need to be in place. Rules rely on two data streams to store their output, API keys to run with the right privileges, and space scoping to keep objects organized. Getting these right upfront means your rules will run cleanly and their output will be queryable from the start.
16+
17+
If you want to jump straight to creating a rule, go to [Quick start](quick-start-alerting.md). For privilege requirements, refer to [Experimental alerting features privileges](alerting-privileges.md).
18+
19+
## Enable the experimental alerting features [alerting-set-up]
20+
21+
22+
The experimental alerting features are available in technical preview in {{stack}} 9.5 and in {{serverless-short}}.
23+
24+
<!--[CONTENT NEEDED: UI. Enabling through Advanced Settings is a development-phase mechanism. Update this entire enablement section with the final path before publishing. The "V2 Alerting Preview" navigation label is also a development-phase name and will change.]
25+
-->
26+
27+
## Where rule events are stored
28+
29+
The experimental alerting features automatically create and manage two data streams when the first rule runs. You don't need to create them manually.
30+
31+
| Data stream | What it stores |
32+
|---|---|
33+
| `.rule-events` | A record for every rule evaluation. One document per result row, per run. Never updated in place. |
34+
| `.alert-actions` | Records for acknowledge, snooze, deactivate, fire, suppress, and other audit and suppression tracking. |
35+
36+
Both data streams are hidden system data streams. To query them in Discover, prefix the name with `$`:
37+
38+
```esql
39+
FROM $`.rule-events`
40+
| WHERE rule.id == "<your-rule-id>"
41+
| SORT @timestamp DESC
42+
| LIMIT 10
43+
```
44+
45+
<!--[CONTENT NEEDED: The direct index names `.rule-events` and `.alert-actions` may not be the intended query surface for end users. There is discussion about exposing this data through other methods instead. Confirm the intended access pattern before publishing this section and the [Query alerts in Discover](alerts/query-alerts-and-signals-in-discover.md) page, and update all examples that reference these index names directly.]
46+
-->
47+
48+
After your first rule runs, use the query above in Discover to confirm documents are appearing. If nothing appears after a few seconds, check that the rule is enabled and that your ES|QL query returns results when run independently.
49+
50+
## Spaces [spaces-for-alerting]
51+
52+
Rules and action policies are space-scoped. Objects you create in one space are not visible in another. Alert events are stored globally, but the UI filters what you see by space.
53+
54+
## API keys [alerting-privileges]
55+
56+
57+
Saving a rule or action policy automatically creates an API key that is used to run it. The key inherits the privileges of the user who saved the object. If those privileges change over time, update the key from the rule or policy management UI.
58+
59+
## Next steps
60+
61+
When you're ready to go further, these can be done in any order:
62+
63+
<!-- TODO: Uncomment when PR #6523 (rules) is merged:
64+
- **[Author rules](rules/author-rules.md):** Write the {{esql}} query that defines what to detect, choose Detect or Alert mode, and configure grouping and thresholds in [Configure a rule](rules/configure-a-rule.md).
65+
-->
66+
<!-- TODO: Uncomment when PR #6525 (workflows/notifications) is merged:
67+
- **[Set up workflows](workflows-alerting.md):** Configure the automation objects that deliver messages — email, Slack, webhook, and so on. You need at least one workflow before action policies can send anything.
68+
- **[Create action policies](notifications/create-configure-action-policy.md):** Define who gets notified, how often, and under what conditions. Policies use KQL matchers to pick up the right episodes and route them to your workflows.
69+
-->

‎explore-analyze/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,9 @@ toc:
380380
- file: report-and-share/reporting-troubleshooting-pdf.md
381381
- file: alerting.md
382382
children:
383+
- file: alerting/kibana-alerting-experimental/quick-start-alerting.md
384+
- file: alerting/kibana-alerting-experimental/setup-alerting.md
385+
- file: alerting/kibana-alerting-experimental/alerting-privileges.md
383386
- file: alerting/alerts.md
384387
children:
385388
- file: alerting/alerts/alerting-getting-started.md

0 commit comments

Comments
 (0)