[Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications#6525
Open
nastasha-solomon wants to merge 36 commits into
Open
[Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications#6525nastasha-solomon wants to merge 36 commits into
nastasha-solomon wants to merge 36 commits into
Conversation
3 tasks
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: 3 warnings, 15 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/workflows-alerting.md | 13 | Elastic.EndPuntuaction | Don't end headings with punctuation. |
| explore-analyze/alerting/watcher/actions.md | 150 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 362 | Elastic.Spelling | 'unsnoozed' is a possible misspelling. |
💡 Suggestions (15): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/about-action-policies.md | 71 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/action-policy-reference.md | 87 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/create-configure-action-policy.md | 59 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/create-configure-action-policy.md | 63 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 8 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 13 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 19 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 21 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/review-execution-history.md | 45 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/notifications-actions.md | 36 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/watcher/actions.md | 150 | Elastic.FirstPerson | Use caution when using first-person pronouns such as 'me.' |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 407 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 410 | Elastic.WordChoice | Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI. |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 412 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 436 | Elastic.WordChoice | Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI. |
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.
Adds six pages under kibana-alerting-experimental/: - workflows-alerting.md: workflow overview and runtime execution order - notifications.md: action policy overview with dispatcher behavior - notifications/create-configure-action-policy.md: creation guide - notifications/action-policy-reference.md: full field reference - notifications/manage-action-policies.md: management operations - notifications/notification-gating.md: acknowledge/snooze/deactivate gating Incorporates additions from PR #6395 including the new notification-gating page. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
force-pushed
the
alerting/experimental-workflows
branch
from
2b99342 to
9bdc843
Compare
2 tasks
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
changed the title
…6639) <!-- 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. --> Updates the action policy docs for the experimental alerting features with content from eight doc issues. Following the tech preview principle of accuracy over comprehensiveness, changes focus on stable concepts and system behavior rather than UI details that are subject to change. ### Per-rule action policies ([#6613](#6613)) The most significant conceptual change in this batch. The previous docs described all action policies as global within a space. PR #268006 introduced a `global` / `single_rule` type discriminator, making the existing description factually incorrect. **`notifications.md`** — Updated "What is an action policy" to define both policy types, their scoping rules, and when to use each. Updated "How policies apply to rules" to distinguish global and per-rule scoping. Updated "Why policies are separate from rules" to reflect that per-rule policies exist for rule-specific routing. **`create-configure-action-policy.md`** — Added a **Policy type** field section explaining the global/per-rule distinction, the immutability constraint, and when to choose each type. Updated the opening paragraph and the match conditions scope description to reflect both types. ### Policy tags ([#6616](#6616)) PR #261008 added a `tags` field to notification policies across the full stack. **`create-configure-action-policy.md`** — Added a **Tags** field section explaining that policy tags are organizational labels distinct from rule tags and do not affect routing behavior. ### Quick filter KQL fields ([#6608](#6608)) PR #261601 added Rule, Status, and Tags quick filter pickers to the match conditions form. The pickers generate `rule.id`, `episode_status`, and `rule.tags` KQL respectively. **`action-policy-reference.md`** — Added `rule.tags` to the match conditions field reference table. This field was missing but is now surfaced by the quick filters and used in examples across the docs. **`create-configure-action-policy.md`** — Updated the match conditions example from `data.severity` to `rule.tags: "payment-service"` to reflect the fields that quick filters generate. ### Maintenance window suppression ([#6416](#6619)) PR #267771 added backend suppression logic for maintenance windows in the dispatcher. **`action-policy-reference.md`** and **`notifications.md`** — Updated the `suppressed` dispatch outcome description to include maintenance windows as a cause alongside acknowledge, snooze, and deactivate. ### View policy details ([#6419](#6619)) PR #264497 added a details flyout to the Action policies list page. **`manage-action-policies.md`** — Added a "View policy details" section describing that a policy's full configuration and all per-policy actions are accessible from the list page. UI mechanics (flyout vs. dedicated page) are omitted as the IA is not yet stable. ### Policy execution history ([#6501](#6501)) PR #266775 added a Policy Execution History UI and API. **`manage-action-policies.md`** — Added an "Execution history" section describing how to query dispatch outcomes per policy using the `.alert-actions` data stream. The section points to the existing dispatch outcomes reference rather than documenting the UI, which is subject to change. ### Out of scope for this PR - **[#6498](#6498 (optional `matcher` query parameter on the data fields suggestions endpoint): API reference detail with no conceptual home yet. - **[#6617](#6617 (grouping modes and frequency strategies redesign): The existing reference and create-configure pages already cover this content accurately. No new stable concepts to add at the tech preview stage. ## 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: -->
kdelemme
reviewed
May 27, 2026
…tions.md Co-authored-by: Kevin Delemme <kdelemme@gmail.com>
This was referenced Jul 2, 2026
nastasha-solomon
added a commit
that referenced
this pull request
Jul 2, 2026
…ontent (#7180) ## 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
nastasha-solomon
added a commit
that referenced
this pull request
Jul 3, 2026
## Summary Updates `setup-alerting.md` and `alerting-privileges.md` for the experimental alerting system with the confirmed M2 enablement procedure and RBAC privilege requirements. Following the tech preview principle of accuracy over comprehensiveness, additions focus on stable behavior — how to turn the feature on, what the setting controls, what happens when it's turned off, and which privilege controls which action. --- ## Content changes ### RBAC privilege requirements (closes #6043) Kibana PRs #270574 and #272440 introduced four standalone privileges under the **Alerting** category in Kibana role management: **Rules**, **Alerts**, **Action Policies**, and **Execution history**. Each privilege is independent; holding one does not grant another. **`alerting-privileges.md`** — Replaced all four `[CONTENT NEEDED]` placeholders with full privilege documentation: * **Manage rules** — privilege table (All: create, edit, delete, enable, and disable rules; Read: view rules) with guidance on when each level applies. * **Manage action policies** — privilege table (All: create, update, delete, snooze, and unsnooze; Read: view) with an explicit callout that **Rules: All** does not include action policy management. * **Manage alerts** — privilege table (All: acknowledge, snooze, assign, tag, activate, and deactivate alert episodes; Read: view) with triage use case. * **View execution history** — new section documenting that both All and Read grant identical read-only access. There is no write surface for execution history. * **Query alert data in Discover** — Kibana **Discover: Read** access plus `read` index privilege on `.rule-events` and `.alert-actions`, with a note to use a custom role for hidden system data streams. Also updated the opening paragraph from "control which users can" to "control what you can do with" to use second-person voice, consistent with the style applied across the other sections. What was omitted: role management UI steps (subject to change before GA), specific custom role configuration procedures, and any serverless-specific privilege differences not yet confirmed. --- ### Enable the experimental alerting system (closes elastic/docs-content-internal#1113) Kibana PR #272365 consolidated experimental alerting feature flags under a single `alerting:v2:enabled` advanced setting. **`setup-alerting.md`** — Replaced the "CONTENT NEEDED" placeholder in the **Enable the experimental alerting system** section with the confirmed M2 enablement procedure: * **Stack path**: Stack Management → Advanced Settings → Global settings → toggle on **alerting:v2:enabled**. * **Serverless path**: No Global Advanced Settings UI exists in serverless. Documents the `POST kbn:/internal/kibana/global_settings` Dev Tools call with a note that the endpoint is internal and has no public equivalent. * **Disabled-state behavior**: When the setting is off, rule and dispatcher execution stops, the APIs and UIs are hidden, and existing rules and action policies are paused. Turning it back on resumes execution. Disabling does not delete any data. What was omitted: the `kibana.yml` prerequisite (configured by default; no action needed), non-YAML UI steps for serverless (no UI exists), and the internal Kibana issue tracking the default enablement (elastic/rna-program#606). ### Stale CONTENT NEEDED comment removed **`setup-alerting.md`** — Removed the "CONTENT NEEDED" comment from the **Where rule events are stored** section. The comment flagged uncertainty about whether `.rule-events` and `.alert-actions` would be the intended query surface for end users. This is now confirmed: both data streams are the documented query surface, as reflected in the [Query alert history in Discover](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6527/explore-analyze/alerting/kibana-alerting-experimental/alerts/query-alerts-and-signals-in-discover) page in PR #6527. ### Stale TODO paths fixed **`setup-alerting.md`** — Fixed two broken cross-reference paths in the commented-out **Next steps** links: * `rules/author-rules.md` → `rules/create-a-rule.md`. The `author-rules.md` page was deleted in PR #6523; `create-a-rule.md` is the new entry point to the rules section. * `notifications/create-configure-action-policy.md` → `action-policies/create-configure-action-policy.md`. The directory structure for action policies changed in PR #6525. * Updated "Detect or Alert mode" → "Signal or Alert mode" to match the renamed rule kind label from PR #6523. ### Opening intro updated Removed the "Set up is part of the experimental alerting system in Kibana" anchor sentence and split the opening paragraph in two for scannability. Updated "need to be enabled" to "must be enabled" for imperative clarity. --- ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? * Yes — Cursor + Claude * No
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
miguelmartin-elastic
left a comment
miguelmartin-elastic
left a comment
There was a problem hiding this comment.
I added a couple of comments. The main one is regarding the recent changes in the Execution History page. Let me know if I can help with anything. TIA!
|
|
||
| Episodes that were acknowledged, snoozed, marked inactive, or covered by a maintenance window are suppressed before the dispatcher runs and produce no event log entry. | ||
|
|
||
| `unmatched` appears in the event log but isn't available as an outcome filter in the **Execution history** UI. To find `unmatched` records, open Discover, query `.kibana-event-log-*`, add a filter for `event.provider: "alerting_v2"`, and filter `event.action: "unmatched"`. |
| |---|---| | ||
| | **Timestamp** | When the dispatcher ran. | | ||
| | **Policy** | The action policy that was evaluated. | | ||
| | **Rule** | The rule whose alert episodes the policy processed. | |
There was a problem hiding this comment.
As mentioned here, this column is now plural "Rules"
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
Adds documentation for notifications, action policies, and workflow connections for the experimental alerting system, contributing to docs-content-internal#919. Following the tech preview principle of accuracy over comprehensiveness, pages focus on stable concepts — what the system does, when to choose each feature, and how the components connect — rather than UI-level procedures that are subject to change before GA.
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. 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.
✏️ Editorial reviewer
This PR adds the full notifications and action policies documentation set for the experimental alerting system. As you're reviewing, please focus on writing quality, clarity, and how the content serves a reader who's seeing this system for the first time. Pay particular attention to the action policy reference, the about-action-policies conceptual page, and the three scenario sub-pages.
Previews
Section landing page
Action policies: conceptual and how-to
Action policy scenarios
Workflows (updated pages)
Generative AI disclosure