[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features overview pages#6521
Open
nastasha-solomon wants to merge 40 commits into
Open
[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features overview pages#6521nastasha-solomon wants to merge 40 commits into
nastasha-solomon wants to merge 40 commits into
Conversation
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
Contributor
Contributor
Elastic Docs Style Checker (Vale)Summary: 2 warnings, 6 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/alerts.md | 21 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
| explore-analyze/alerting/kibana-alerting-experimental/how-it-works.md | 18 | Elastic.DontUse | Don't use 'just'. |
💡 Suggestions (6): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 26 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 26 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 44 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 50 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 53 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/kibana-alerting-experimental/glossary.md | 59 | Elastic.Semicolons | Use semicolons judiciously. |
The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.
- alerting.md: updated section overview for all three alerting systems - alerting/choose-an-alerting-system.md: new comparison and selection guide - alerting/kibana-alerting-experimental.md: new experimental alerting features overview with concepts glossary and Dispatcher entry - explore-analyze/images/rule-alert-mode-diagram.png, rule-detect-mode-diagram.png: new diagrams - toc.yml: navigation entries for new pages Applies naming guidelines throughout. Cross-references to pages in later PRs are commented out with TODO notes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
force-pushed
the
alerting/experimental-overview
branch
from
5e76dfb to
ff31898
Compare
nastasha-solomon
added a commit
that referenced
this pull request
May 15, 2026
…6521 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 tasks
nastasha-solomon
added a commit
that referenced
this pull request
May 15, 2026
…fter PR #6521 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
changed the title
…lastic/docs-content into alerting/experimental-overview
mdbirnstiehl
approved these changes
Jul 2, 2026
mdbirnstiehl
left a comment
mdbirnstiehl
left a comment
Member
There was a problem hiding this comment.
Did a little editorial review and everything LGTM!
tiamliu
approved these changes
Jul 2, 2026
…moves detailed mode walkthrough to new page (#7208) <!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Refines the experimental alerting system overview page and adds a new "How it works" reference page for readers who want a detailed breakdown of the system's execution flow. ### Reasoning for changes The overview page was doing two jobs at once — introducing the system to new readers and documenting the detailed execution flow for people who needed to understand the mechanics. Mixing those audiences on one page made both experiences worse: the intro felt cluttered and the technical detail was hard to find. This change splits the two. The overview stays focused on what the system is and how the pieces relate, using plain language that works for someone seeing it for the first time. The new "How it works" page gives engineers and technically curious readers a clean step-by-step breakdown of what each component does at each stage, organized by rule mode, with a note on the dispatcher's independent polling cycle that the original ASCII diagrams obscured rather than clarified. The practical result is that a new user reading the overview gets a cleaner introduction, and someone debugging a notification delay or trying to understand the execution order has a dedicated page they can go to directly. ### kibana-alerting-experimental.md - Added a plain-language "How the pieces fit together" section that explains the rule-to-episode-to-action-policy-to-workflow flow at a high level before the mode-specific detail. - Rewrote the Alert and Signal mode descriptions to be accurate about the polling-based execution model and accessible to readers who are new to the system. - Removed ASCII flow diagrams and the detailed Alert/Signal mode sections, which are now covered by the new how-it-works.md page. - Added a reference to how-it-works.md at the end of the "How the pieces fit together" section. ### kibana-alerting-experimental/how-it-works.md (new) - Documents the step-by-step execution flow for Alert mode (9 steps) and Signal mode (3 steps) using actor/action tables instead of ASCII diagrams. - Includes a note clarifying that action policy evaluation (steps 4–6 and 8–9) runs on a separate background process that polls roughly every 5 seconds, not synchronously with the rule's execution. - Includes concrete examples for each mode. ### Other - Deleted rule-alert-mode-diagram.png and rule-detect-mode-diagram.png (no longer referenced). - Updated toc.yml to add how-it-works.md as a child of the overview page. ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: -->
Member
Author
|
@tiamliu @jasonrhodes heads up that I made one more small adjustment to the overview page in the latest commit: The overview page was doing two jobs at once: introducing the system to new readers and documenting the detailed execution flow for people who needed to understand the mechanics. Mixing those audiences on one page is not ideal. The latest commit keeps the overview focused on what the basics (what the new system is and how the pieces interact) and targets users encountering the system for the first time. The new "How it works" page targets more technical folks (engineers, analysts, SREs) and gives them more detailed explanations of what happens at each stage of alerting v2 workflows. This is particularly helpful for a user who wants to better what happens under the hood or need some additional context for troubleshooting. |
tiamliu
approved these changes
Jul 6, 2026
nastasha-solomon
commented
Jul 8, 2026
nastasha-solomon
commented
Jul 8, 2026
Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Contributes to https://github.com/elastic/docs-content-internal/issues/919. This PR adds the overview pages that introduce the experimental alerting system alongside Elastic's existing alerting options, and a dedicated "How it works" page for readers who want a detailed breakdown of the system's execution flow.
Navigation structure
Review requests
This PR needs a technical and editorial review. Instructions for each are below.
🔧 Technical reviewer
Please focus your review on accuracy of facts, names, and structure only. Verify that field names, values, and descriptions in reference material are accurate and match the current implementation. When reviewing conceptual material, check that definitions are technically accurate and reflect the current engineering design. Pay particular attention to:
kibana-alerting-experimental.md, especially the plain-language explanation in the "How the pieces fit together" section.how-it-works.md, including the note that action policy evaluation (steps 4–6 and 8–9) runs on a separate dispatcher polling cycle, not synchronously with the rule's execution.kibana-alerting-experimental.mdandglossary.md, which reflects the merged (non-global/non-per-rule) policy model.glossary.md.choose-an-alerting-system.md, especially Rule definition (rule builders + ES|QL), Notifications (action-level throttling), and Build highly custom notification logic (workflows row).✏️ Editorial reviewer
This PR adds five pages: an overview of the system with plain-language mode explanations, a step-by-step "How it works" reference page, a dedicated glossary, a comparison and selection guide across all Elastic alerting systems, and a revised
alerting.mdthat frames all options for readers arriving at the section root.Please focus on writing quality, clarity, and how the content serves a reader who is seeing this system for the first time. Pay particular attention to the overview page and the "How it works" page, which are the two pages a new user is most likely to read together.
🚫 What to skip for now
Do not flag or review any section marked
[CONTENT NEEDED]or with aTODOcomment — intentionally incomplete pending UI finalization or incoming PRs.Previews — 📁 New v2 content
Overview and navigation
Generative AI disclosure