[Alerting V2][Serverless & 9.5][M2] Setup changes from July 2

[nastasha-solomon]

Summary

Reorganizes and rewrites the experimental alerting system onboarding documentation. Three standalone pages (setup-alerting.md, alerting-privileges.md, quick-start-alerting.md) are replaced with a structured Get started section modeled on the Workflows documentation pattern. New global variables are added to docset.yml and toc.yml is updated to reflect the new hierarchy.

---

Navigation structure

kibana-alerting-experimental/
├── get-started.md                      ← new landing page
└── get-started/
    ├── setup.md                        ← was setup-alerting.md
    ├── configure-access.md             ← was alerting-privileges.md
    └── create-your-first-rule.md       ← was quick-start-alerting.md

The three source files (setup-alerting.md, alerting-privileges.md, quick-start-alerting.md) are deleted.

---

Content changes

docset.yml

Added two new global variables:

• alerting-v2-system: "experimental alerting system"
• alerting-v2-system-cap: "Experimental alerting system"

All alerting v2 pages now use {{alerting-v2-system}} and {{alerting-v2-system-cap}} consistently in place of the previous {{alerting-v2}} and {{alerting-v2-cap}} variables.

---

get-started.md (new)

New landing page that introduces the Get started section and links to the three child pages with one-line descriptions of what each covers.

---

get-started/setup.md (replaces setup-alerting.md)

Documents how to turn the alerting:v2:enabled advanced setting on and off, organized into three sections:

• Turn on the system: Tabbed instructions for Stack (Advanced Settings UI) and Serverless (Dev Tools API call). Each tab states the required role (kibana_admin for Stack; admin project role for Serverless) and the steps separately. Includes a note that the internal API endpoint has no public equivalent.
• Confirm the UI is accessible: Steps to verify the system is accessible via the global search field after enabling. Notes that a page refresh may be needed.
• Turn off the system: Explicit per-deployment instructions (toggle in Advanced Settings for Stack; API call for Serverless). Lists what stops and what is preserved when the setting is off (rules and action policies remain as saved objects; data in .rule-events and .alert-actions is preserved).

Also includes a Next steps section pointing to configure-access.md, with commented-out links to rules and notifications content pending PRs #6523 and #6525.

---

get-started/configure-access.md (replaces alerting-privileges.md)

Replaces the original placeholder-based privilege page with full privilege documentation. Content is organized by user activity rather than by feature category:

Quick reference table: Maps five user activities (author and manage rules, monitor rule execution, triage alert episodes, configure notifications, query rule output and episode data) to their minimum required privileges. Includes a note that roles may also need read index access on source indices and Actions and Connectors: All depending on configuration.

Alerting feature privileges (under Alerting in role management):

• Rules: All vs. Read, with a note that Rules: All also grants access to the Alerts menu in Discover for rule creation routing.
• Execution history: Read-only; All and Read grant identical access.
• Alerts: All (triage actions) vs. Read (view).
• Action policies: All vs. Read, with a note that Action Policies: All does not include Rules management.
• Workflows: Set under Analytics > Workflows, not Alerting. Required alongside Action Policies to create or manage action policies.

Discover and data access (under Analytics in role management):

• Kibana Discover: Read (All and Read are equivalent for query access; no write surface).
• Elasticsearch index access on three data streams: .rule-events (rule evaluation records), .alert-actions (episode triage actions), .kibana-event-log-* (action policy dispatch outcomes).

---

get-started/create-your-first-rule.md (replaces quick-start-alerting.md)

Complete rewrite as a hands-on tutorial using a P95 latency monitoring scenario. The tutorial walks through the full alert episode lifecycle from setup to automatic recovery.

Prerequisites: Enable the system (links to setup.md), configure access with Rules: All and Discover: Read + .rule-events index privilege (links to Kibana role management).

Tutorial steps (using the :::::{stepper} component):

1. Create the index: PUT checkout-service-logs with explicit mapping (keyword, date, float fields).
2. Load sample data: ~80 bulk documents spanning healthy (P95 ≈ 400 ms), degraded (P95 2000–4400 ms across three consecutive 5-minute windows), and recovered phases. Data is in a collapsible dropdown. Includes a note about fixed timestamps and find-and-replace instructions for updating the date.
3. Create the rule (using the Create ES|QL rule path in the rule authoring flyout):
   • Query sandbox: pastes the P95 PERCENTILE query with CASE severity tiers, sets date range to Last 1 hour, verifies results, applies changes.
   • Pane 1 (Alert Condition): sandbox auto-fills Mode, Time field, and Group fields. User sets Alert delay to Breaches: 2, Schedule to 5 minutes, and Lookback Window to 2 hours (required to reach fixed-timestamp sample data).
   • Pane 2 (Recovery Condition): confirms Default recovery + Immediate delay defaults.
   • Pane 3 (Details & Artifacts): sets name (Checkout Service Latency) and description.
   • Pane 4 (Actions): skips — rules and action policies are decoupled; no action policy is required.
4. Confirm the rule is evaluating: Opens Discover in ES|QL mode, sets date range to Today or Last 1 hour, queries .rule-events by rule ID, checks status, episode.status, data.service.name, and data.severity fields.
5. Observe the episode lifecycle: Explains how the lookback window slides forward until the degraded data ages out, queries episode status, and confirms automatic recovery to inactive.

Key concepts demonstrated: Rules, severity tiers (CASE expression), episode lifecycle (Alert delay: Breaches), automatic recovery (Default recovery), rule events as queryable history.

---

toc.yml

Replaced the flat list of three source files under alerting.md with a parent-child hierarchy:

- file: alerting/kibana-alerting-experimental/get-started.md
  children:
    - file: alerting/kibana-alerting-experimental/get-started/setup.md
    - file: alerting/kibana-alerting-experimental/get-started/configure-access.md
    - file: alerting/kibana-alerting-experimental/get-started/create-your-first-rule.md

---

Out of scope

• Rules reference docs (PR [Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages #6523)
• Action policies and notifications docs (PR [Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications #6525)
• Alerts/Discover query docs (PR [Alerting V2][Serverless & 9.5][M2] Add experimental alerting features alerts pages #6527)
• Links to those pages are present but commented out with TODO notes throughout

---

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes — Cursor + Claude
• No

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.