[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features alerts pages#6527
Open
nastasha-solomon wants to merge 25 commits into
Open
[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features alerts pages#6527nastasha-solomon wants to merge 25 commits into
nastasha-solomon wants to merge 25 commits into
Conversation
Adds four pages under kibana-alerting-experimental/alerts/: - alerts.md: section index covering alert lifecycle and .alert-actions - alerts/view-and-manage-alerts.md: triage, acknowledge, snooze, bulk actions - alerts/alert-states-and-fields-reference.md: episode states and field reference - alerts/query-alerts-and-signals-in-discover.md: ES|QL query guide Incorporates additions from PR #6395. Cross-references to pages in other PRs are commented out with TODO notes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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. |
…6521 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 tasks
…fter PR #6521 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
Contributor
Elastic Docs Style Checker (Vale)Summary: 2 warnings found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/alerts/triage-alert-episodes.md | 18 | Elastic.Spelling | 'Unacknowledge' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-experimental/alerts/triage-alert-episodes.md | 22 | Elastic.Spelling | 'Unresolve' is a possible misspelling. |
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.
nastasha-solomon
changed the title
…th of May and June 3 (#6847) <!-- 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. --> Ports changes from #6686 and adds docs for #6690 and #6838. ## 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: -->
…7078) ## Summary Updates alerting docs for the experimental alerting system with content from five M2 doc issues, plus a structural restructuring of the alerts documentation set. Following the tech preview principle of accuracy over comprehensiveness, additions focus on stable concepts — what these features help users understand, when to use them, and how they fit into the system. --- ## Structural changes ### `view-and-manage-alerts.md` split into three pages The original page covered too many distinct tasks in a single file. It has been split into: - **`view-and-manage-alerts.md`** (retained as parent) — Now scoped to the overview of the Alerts UI: space scoping, KPI panels, episode histogram, and filter/search. Links forward to the two child pages. - **`triage-alert-episodes.md`** (new) — Covers all triage actions: acknowledge, snooze, resolve, activate, edit tags, assign, bulk actions, Open in Discover, and the action scope reference table. - **`investigate-alert-episodes.md`** (new) — Covers the episode detail page: metric trend, related episodes by series, source event metadata, response history and actors, and episode assignment. ### `alert-states-and-fields-reference.md` renamed to `field-reference.md` Renamed to better reflect the page's purpose as a field schema reference rather than a state reference. New H1 title: "Alert data stream field reference". The standalone status values section was removed; status values and accepted values are now documented inline in each field's description column. Both tables were updated from four columns to three (Field, Type, Description) following standard reference conventions. ### `alert-data-model.md` added (moved from `alerts.md`) The "Where alerts live" and "Signals versus alerts" content was extracted from `alerts.md` into a new dedicated page explaining the foundational data model: what the system writes, where it writes it (`.rule-events` and `.alert-actions`), and how rule mode determines whether a document is a signal or an alert. ### `toc.yml` restructured The nav hierarchy now reflects the logical grouping of pages: ``` alerts.md ├── view-and-manage-alerts.md │ ├── triage-alert-episodes.md │ └── investigate-alert-episodes.md └── query-alerts-and-signals-in-discover.md ├── alert-data-model.md └── field-reference.md ``` --- ## Content changes ### Metric trend for threshold rules on the episode detail page (#7160) Kibana PR #275034 adds a trend panel to the episode detail page that plots the metric values evaluated by a rule over the episode's time range, alongside the threshold values from the rule conditions. The panel is only present for threshold-based rules. **`alerts/investigate-alert-episodes.md`** — Added a "Metric trend" section documenting: what the trend view shows (evaluated metric versus threshold conditions over the episode's lifetime), the multi-condition grouping behavior (same metric → combined view; different metrics → separate views per metric), and the conditional visibility rule (absent for signal-mode rules and rules without comparable metric output). What was omitted: panel position relative to other elements, visual styling of threshold lines, badge selector UI for switching between metrics, and flyout versus full-page behavior differences. ### Histogram chart and KPI panels on the alert episodes list (#6872, #6876) PR #270922 added a histogram chart above the alert episodes table. PR #271147 added two KPI stat panels to the same page. **`alerts/view-and-manage-alerts.md`** — Added a "Monitor alert health and trends" section covering KPI panels (aggregate counts that update as filters change) and the episode histogram (trend over time, breakdown by dimensions). Includes a `:::note` block for the 10,000-episode query cap. A `<!-- CONTENT NEEDED -->` comment flags that specific KPI panel labels and layout should be documented once the UI stabilizes before GA. What was omitted: specific KPI metric labels by panel name, all histogram breakdown option names, color coding for status badges, and URL persistence of selections. ### Discover Alerts menu access and v2 flyout routing (#6878, #7010) PR #267469 fixed a bug where the Discover Alerts menu was hidden for users with only `{{alerting-v2-system}}` access. PR #272724 redesigned the Alerts menu and routes rule creation to the v2 rule form when `{{alerting-v2-system}}` is enabled. **`alerts/query-alerts-and-signals-in-discover.md`** — Added a "Create rules from Discover" section covering the access rule (either Kibana alerting access or `{{alerting-v2-system}}` access is sufficient) and the routing behavior. A `<!-- CONTENT NEEDED -->` comment calls for step-by-step instructions once the rules page is written. What was omitted: specific redesigned menu structure, screenshots, and detailed creation steps. ### Query page improvements **`alerts/query-alerts-and-signals-in-discover.md`** — Multiple improvements throughout: - Added a complete "Before you begin" procedure for creating `.rule-events` and `.alert-actions` data views in Discover, sourced from the existing data views docs with a cross-link. - Rewrote section intros in active voice (attribution to Kibana, not the data streams). - Converted all example queries from bold-label format to `####` subsections with descriptive titles, introductory sentences, and inline `//` comments annotating each meaningful query line. - Updated the "Trace the full story of an incident" section to document the `episode_id` optionality caveat (system-written action types may not carry `episode_id`), explain the naming difference between `episode.id` and `episode_id`, and recommend `group_hash` as the more reliable join key. --- ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - Yes — Cursor + Claude - No
adcoelho
approved these changes
Jul 3, 2026
nastasha-solomon
added a commit
that referenced
this pull request
Jul 5, 2026
…; address issues #1419 and #1420 (#7213) ## Summary Comprehensive edits to the experimental alerting system get-started documentation. Addresses two internal tracking issues ([#1419](elastic/docs-content-internal#1419) — implicit Elasticsearch privilege grant for the Alerts privilege, and [#1420](elastic/docs-content-internal#1420) — setup prerequisites), and applies structural, editorial, and clarity improvements across all four pages in the section. --- ## Content changes ### `get-started.md` Updated the landing page intro and all three child page descriptions to accurately reflect the current content of each page. Updated the frontmatter description. --- ### `get-started/setup.md` - Added a **Requirements** section covering license requirements (Enterprise required for Workflows-based notifications on Stack; no restriction on Serverless), data prerequisites, connectors, and space selection. - Moved the `configure-access.md` cross-reference earlier in the page (after the "Confirm the UI is accessible" step) rather than only in Next steps. - Simplified the "Turn on the system" tab-set by removing the `**Requirement:**` / `**Steps:**` heading pattern and inlining the role requirement. - Updated frontmatter description to reflect the page's actual scope (requirements + on/off mechanics). --- ### `get-started/configure-access.md` Addresses [#1419](elastic/docs-content-internal#1419): - **Quick Reference table**: Split the single "Query rule and episode data in Discover" row into two rows — one for `.rule-events`/`.alert-actions` (access bundled with the Alerts privilege) and one for `.kibana-event-log-*` (still requires a custom role). - **Triage alerts section**: Added a note that granting **Alerts: All** or **Alerts: Read** automatically includes Elasticsearch `read` access to `.rule-events` and `.alert-actions`, with no separate index privilege needed. - **ES index access section**: Rewrote to clarify the access method per data source. `.rule-events` and `.alert-actions` access is bundled with the Alerts privilege; `.kibana-event-log-*` still requires a custom role. Custom-role fallback preserved for the two auto-granted streams. - Added **Next steps** section with a link to the tutorial and commented-out links for notifications and rules content pending PRs #6523 and #6525. --- ### `get-started/create-your-first-rule.md` **Structure:** - Separated environment setup (index creation, sample data) from the rule creation workflow into a dedicated **Prepare your environment** section with its own stepper. - Split the single "Create the rule" stepper step into five focused steps: Open the rule editor, Write and test the detection query, Configure the alert condition, Configure the recovery condition, and Name and save the rule. - Moved "Confirm the rule is evaluating" and "Observe the episode lifecycle" out of the Tutorial stepper and into standalone `##` sections, since they're observational steps after rule creation, not part of the creation workflow itself. **Content:** - Rewrote the page intro to be high-level and inviting, with a numbered task list that previews each section and explains its purpose. - Added a intro paragraph to "Prepare your environment", "Create the rule", and "Observe the episode lifecycle" to orient users before the steps begin. - Added brief explanations for the detection query (what `PERCENTILE`, `CASE`, and `WHERE` do) and the lifecycle query (what `STATS ... BY` produces), for readers new to ES|QL. - Simplified time-phase descriptions (removed redundant minute-count approximations; standardized on clock times). - Shortened and simplified the timestamp update note. - Improved sandbox recovery preview explanation — framed as a preview of recovery behavior rather than a "verification step." - Fixed step numbering bug in "Observe the episode lifecycle" (step `3` was mislabeled). **Requirements section** (addresses [#1420](elastic/docs-content-internal#1420)): - Replaced the manual `read` index privilege on `.rule-events` with **Alerts: Read**, noting that this automatically grants Elasticsearch access with no separate index privilege needed. - Added **Discover: Read** as an explicit requirement. - Added `create_index` and `write` index privileges on `checkout-service-logs`. - Reformatted requirements as a table (Task / Required privilege) for scannability. **Editorial:** - Removed all em dashes throughout. - Replaced `"via"` with `"using"`. - Replaced bold-header prose blocks with properly structured lists and tables. --- ## Out of scope - Rules reference docs (PR #6523) - Action policies and notifications docs (PR #6525) - Alerts/Discover query docs (PR #6527) - ECH-specific setup behavior for the `xpack.alerting_v2.enabled` flag (pending engineering confirmation; placeholder comment left in `setup.md`) --- ## Generative AI disclosure - Yes — Cursor + Claude
…riage-alert-episodes.md
umbopepato
reviewed
Jul 7, 2026
umbopepato
reviewed
Jul 7, 2026
|
|
||
| ## Source event metadata [source-event-metadata] | ||
|
|
||
| The metadata view surfaces field values from the source event that triggered the episode. Use it to inspect fields that aren't shown in the main detail view, such as resource identifiers or version information. |
Member
There was a problem hiding this comment.
nit: we might want to specify that this is not a complete and exact representation of the source data that triggered the event, but of the data that resulted from the rule query. I.E. if in my query I do STAT ... BY I'll get the stats in the stored metadata, not all the fields of the source document. Users might expect the whole doc to be there, but they'll get whatever they compute or KEEP in the query
Member
Author
There was a problem hiding this comment.
@umbopepato if users wanted to see the full source doc, how would they do that from the metadata view? For example, should they open the alert episode in Discover or take another path?
Member
Author
There was a problem hiding this comment.
Comment is partially addressed in Addressed in 491edf9 (this PR). One item is left.
umbopepato
approved these changes
Jul 7, 2026
umbopepato
left a comment
umbopepato
left a comment
Member
There was a problem hiding this comment.
LGTM! 🚀
Left some minor comments
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
3 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
Adds the complete alerts documentation set for the experimental alerting system, contributing to https://github.com/elastic/docs-content-internal/issues/919. Following the tech preview principle of accuracy over comprehensiveness, pages focus on stable concepts — what alert episodes are, how they move through lifecycle states, and how to triage, investigate, and query them — rather than step-by-step UI procedures that are subject to change before GA.
Navigation structure
The alerts section is organized as a section index with child pages that follow a concept → task → reference progression.
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. Verify that field names, values, and descriptions in reference material match the current implementation. When reviewing conceptual content, check that definitions are technically accurate and reflect the current engineering design. Pay particular attention to the lifecycle state machine in
alerts.md, the triage action scope table intriage-alert-episodes.md, the field schemas infield-reference.md, and the metric trend conditional visibility logic ininvestigate-alert-episodes.md.✏️ Editorial reviewer
This PR adds the complete alerts documentation set for the experimental alerting system. As you're reviewing, please focus on writing quality, clarity, and how the content serves a reader seeing this system for the first time.
Previews - 📁 New v2 content
Section index
Background
.rule-eventsand.alert-actions)View, triage, and investigate
Query guide
Reference
.rule-eventsand.alert-actions; allaction_typevaluesGenerative AI disclosure