[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages#6523
Open
nastasha-solomon wants to merge 36 commits into
Open
[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages#6523nastasha-solomon wants to merge 36 commits into
nastasha-solomon wants to merge 36 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
🔍 Preview links for changed docs⏳ Building and deploying preview... View progress This comment will be updated with preview links when the build is complete. |
Contributor
Elastic Docs Style Checker (Vale)Summary: 8 suggestions found 💡 Suggestions (8): Optional style improvements. Apply when helpful.
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 ten pages under kibana-alerting-experimental/rules/: - rules.md: section index - author-rules.md, esql-query-patterns.md: authoring guides - create-rule-from-rule-builder.md, create-rule-from-discover.md, create-rule-with-yaml.md: creation workflows - yaml-rule-schema-reference.md: complete YAML field reference - configure-a-rule.md, view-manage-rules.md: management pages - rule-event-field-reference.md: .rule-events document field reference 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-rules
branch
from
f179a94 to
085cf67
Compare
2 tasks
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
changed the title
#6687) ## Summary Updates the rules docs for the experimental alerting features with content from doc issues addressed across two phases of work. Following the tech preview principle of accuracy over comprehensiveness, changes focus on stable concepts — what the system does, when to use each feature, how creation paths work — rather than UI-level procedures that are subject to change before GA. ### Naming conventions and variable corrections (all files) Systematic corrections across all nine rules pages and `docset.yml` to bring variable names, H1 titles, and anchor sentences into line with the naming guidelines. **`docset.yml`** — Renamed `alerting-v2` → `alerting-v2-system` and `alerting-v2-cap` → `alerting-v2-system-cap` to match the naming cheat sheet prescription ("experimental alerting system" in prose). **All rules files** — Updated all occurrences of `{{alerting-v2}}` to `{{alerting-v2-system}}`. Removed "the" from H1 titles where the variable appears (title convention: no article). Updated four anchor sentences that used gerund subjects (`Authoring rules is part of...`, `Configuring rules is part of...`, `Viewing and managing rules is part of...`, `Creating rules from Discover is part of...`) to concrete noun subjects (`Rule authoring is part of...`, `Rule configuration is part of...`, `Rule management is part of...`, `Discover-based rule creation is part of...`). Added the system name to H1 titles on three pages that were missing it (`create-rule-from-discover.md`, `create-rule-from-rule-builder.md`, `create-rule-with-yaml.md`). Added `{{alerting-v2-system}}` to the `rule-event-field-reference.md` H1, which was the only page missing the variable entirely. ### Rule kind label: "Detection only" renamed to "Signal" (#6837) PR #272140 renamed the rule kind label from "Detection only" to "Signal" in the action policy filter dropdown and the episode details rule overview panel. **`author-rules.md`** — Updated the rule mode table: `Detect (kind: signal)` → `Signal (kind: signal)`. **`configure-a-rule.md`** — Updated the rule mode table: `Detect` → `Signal`. Updated the action policy note: "Detect-mode rules" → "Signal-mode rules". **`rules.md`** — Updated all prose references from "Detect mode" to "Signal mode", including the conceptual description and the Next Steps link text. ### Flyout-only rule authoring and creation paths (#6612, #6500, #6607) PR #269629 removed standalone full-page rule form routes. All rule creation and editing now happens through a flyout. PR #267779 introduced the three-path onboarding panel, and PR #269156 wired the Create ES|QL rule card to open the flyout inline rather than navigate to a page. **`rules.md`** — Added a **Create a rule** section establishing that all rules are created through a flyout (never a full-page form) and describing the three starting points at a conceptual level: Create ES|QL rule, Create with AI Agent, and Start from a rule builder. Added a third Next Steps link pointing to `configure-a-rule.md`. **`create-rule-from-rule-builder.md`** — Added a **Creation paths** section documenting the three options on the rule creation panel, with guidance on when to choose each. ### Threshold Alert rule builder (#6832, #6835) **`create-rule-from-rule-builder.md`** — Added a **Threshold Alert** section documenting the first available rule builder type: structured form fields generate the ES|QL query automatically, rules created through the builder can be reopened in builder mode as long as the underlying ES|QL hasn't been edited directly, and a graceful fallback to the ES|QL editor applies when it has. Added a **Recovery conditions** subsection explaining that the builder auto-derives recovery conditions by flipping the alert comparators (a `greater than` alert condition produces a `less than or equal to` recovery condition), and that these are preserved correctly when reopening a rule for editing. ### Form/YAML toggle in the rule authoring flyout (#6606, #6418) PR #269150 added a YAML editing mode to the Compose Discover flyout, and PR #265929 added the toggle to the Discover-based flyout. Both share the same sync behavior. **`create-rule-from-rule-builder.md`** — Added an **ES|QL rule: form and YAML editing** section explaining that the Create ES|QL rule path supports both form and YAML modes, that edits are preserved when switching views, that Cancel YAML discards edits and restores prior form state, and that the YAML editor is not available within the Threshold Alert builder or other rule builder types. **`create-rule-from-discover.md`** — Added a matching **Form and YAML editing** section with the same behavioral description, plus a note that the YAML editor includes ES|QL autocomplete in the query field. ### Create rules from Discover (#6614, #6499) PR #260844 added the Create ES|QL rule entry point to the Discover Alerts menu, and PR #268774 introduced the Compose Discover stepped flyout from the rules list. **`create-rule-from-discover.md`** — Added an **Entry points** section documenting both paths into Discover-based rule creation: the Alerts menu in Discover (available only in ES|QL mode) and the rules list. Clarified that the Discover path pre-fills the **Create ES|QL rule** form, not the Threshold Alert builder. Removed a stale cross-reference implying the rule builder holds the YAML toggle. ### Separate alert and recovery conditions (#6605) PR #269023 introduced query splitting for the Compose Discover flow, separating the base data pipeline from the alert condition and adding an explicit Recovery Condition step. **`author-rules.md`** — Added a **Recovery condition** subsection documenting Default (auto-recover when alert condition clears), Custom (separate ES|QL expression), and No recovery (coming soon) types, with guidance on when to use a custom condition over the default. ### AI agent entry points for rule creation (#6604) PR #269588 added Create with agent entry points to both the rules list split button and the rule creation options panel. **`create-rule-from-rule-builder.md`** — Covered as part of the Creation paths section: the AI agent option is described with its use case (plain-language rule definition) and entry point. ### Severity as first-class episode fields (#6689) **`author-rules.md`** — Replaced the convention-based severity description with the M2 first-class `episode.severity` contract: include a `severity` column in ES|QL query output, add it to `KEEP`, and the framework maps it to one of five fixed levels (`info`, `low`, `medium`, `high`, `critical`). Includes an ES|QL example showing the `EVAL severity = CASE(...)` pattern. **`rule-event-field-reference.md`** — Added `episode.severity` and `episode.severity_max` to the episode fields table with descriptions of their behavior and constraints. Removed a stale content-needed comment. **`esql-query-patterns.md`** — Connected the `severity` column in ES|QL query output to the `episode.severity` field stored on the rule event document. Removed stale content-needed comments. ### Action policy creation from the rule form (#6833) **`configure-a-rule.md`** — Updated the action policy note to reflect that Alert-mode rules can now create and attach action policies directly from the rule form's **Actions** step. Clarified that the Actions step is not shown for Signal-mode rules, and that action policies can still be managed independently from the Action policies area. ### Optional recovery policy and no-recovery behavior (#6844) **`yaml-rule-schema-reference.md`** — Added a note to the Recovery policy fields section clarifying that `recovery_policy` is optional. When absent (API or Agent Builder only), the rule emits no recovery events and active alert episodes don't close automatically. Rules created through the Kibana UI always include `recovery_policy.type: no_breach` by default. Removed a stale content-needed comment. **`configure-a-rule.md`** — Added a note in the Recovery thresholds section cross-referencing the `recovery_policy.type` default (UI: `no_breach`) versus API omission behavior, with a link to the schema reference. ### Rule Doctor (#6841) **`rules.md`** — Added **Rule Doctor** to the Next Steps section, describing insight types (duplicates, stale conditions, threshold tuning opportunities, coverage gaps), the open → applied or dismissed lifecycle, and the impact and confidence ratings surface. ### Rule search behavior (#6420, #6615) PR #265303 rewrote the rules list search to use the Saved Objects client's `simple_query_string`, fixing special-character failures. PR #261154 expanded search to match `metadata.description` in addition to `metadata.name`. **`view-manage-rules.md`** — Updated the **Find and filter rules** section to document that search matches rule name and description only using prefix matching (terms AND'd), that tags and grouping fields are displayed in results but aren't full-text searched, and that special characters including consecutive hyphens are handled correctly. ### Quick-edit a rule (#6417) PR #268164 added the Quick Edit flyout, accessible from the pencil icon in a rule row or from the rule summary flyout header. **`view-manage-rules.md`** — Added a **Quick-edit a rule** section documenting editable fields (name, description, tags, grouping key, time field, interval, lookback, alert delay, recovery type, recovery delay) and read-only fields (ES|QL query, alert tracking behavior) in the inline editor. UI entry-point mechanics omitted as the IA is not yet stable. ### Group fields align with STATS...BY (#6415) PR #268522 added auto-population of the Group Fields combobox from the `STATS ... BY` clause as the user types. **`configure-a-rule.md`** — Added a note under **Rule grouping** explaining that writing the query first avoids mismatches between query output and grouping configuration, and that group fields in the form reflect the columns produced by the `STATS ... BY` clause. ## Out of scope for this PR * **#6831** (Alert Delay field in Compose Discover flyout): `configure-a-rule.md` connects `pending_timeframe` to the "Alert delay" UI label. The full Alert Condition step procedure in the Compose Discover flyout is deferred until the flyout UI is stable. * **#6839** (single_rule action policy type via Agent Builder): No docs update required at this time. The `set_type` operation is consumed internally by the AI agent; users interact only through natural language and a rendered card. The `single_rule` policy type and how it differs from a global policy will be documented when action policies reach GA. * **#6012** (no-data handling UI control, serverless only): `configure-a-rule.md` already documents the three `no_data.behavior` values accurately. UI control details deferred. * **#6018** (query preview/test in Discover): Covered by the existing query preview section in `create-rule-from-discover.md`. UI procedure deferred until IA is stable. * **#6603** (action policy support in Agent Builder): Belongs in the action policy docs, not the rules pages. * **#6611** (step indicator in the rule flyout): Minor UI chrome with no stable conceptual content to add at the tech preview stage. * **#6015**: Closed as not planned. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? * Yes - Cursor + Claude sonnet * No --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2 tasks
…ution history docs to rules pages (#7247) ## Summary Adds two missing documentation gaps to the experimental alerting rules section, addressing issues [#7227](#7227) and [#7240](#7240). Both pages are in the in-progress PR [#6523](#6523). --- ## Content changes ### `rules/create-rules-action-policies-agent-builder.md` Addresses [#7227](#7227): Added a **Requirements** section before "Propose and save a rule" covering the three conditions that must be met for the "Create with AI Agent" entry points to appear in the {{alerting-v2-system}} UI: - **The required subscription**: Agent Builder requires the appropriate Stack subscription or Serverless project feature tier. Without it, the entry points are hidden. - **The `agentBuilder:experimentalFeatures` advanced setting turned on**: The alerting v2-specific UI gate, enabled in Advanced Settings. Added following the Kibana PR [#274165](elastic/kibana#274165) which introduced this as a hard gate on all four "Create with AI Agent" entry points (rules list split-button, empty state, and both create-rule flyouts). - **The required privileges**: A table covering the four privilege requirements — `Agent Builder: Read` to access the agent, `Rules: All` to save a rule, `Action Policies: All` to save an action policy, and `Workflows: Read` or `Workflows: All` to select or create a workflow destination. A cross-reference link to `configure-access.md` is included but commented out pending PR [#6522](#6522). Requirements section is modeled on the `create-your-first-rule.md` pattern from PR [#6522](#6522). --- ### `rules/view-manage-rules.md` Addresses [#7240](#7240): Added a **Monitor rule execution health** section documenting the Execution History page and its Rules tab, introduced in Kibana PR [#275066](elastic/kibana#275066). - Describes the Execution History page as a cross-rule view for monitoring rule health at scale. - Documents the two-tab layout: **Rules** (default) and **Policies**. - Documents the **Rules** tab columns: Timestamp, Rule (links to rule summary flyout), Duration, Response, and Message. - Documents the server-side **Outcome** filter (All / Success / Failure) and the 10,000-record result cap. Updated the page description and opening paragraph to reflect the new coverage. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes — Cursor + Claude - [ ] No
…tic/docs-content into alerting/experimental-rules
dominiqueclarke
approved these changes
Jul 8, 2026
dominiqueclarke
left a comment
dominiqueclarke
left a comment
Contributor
There was a problem hiding this comment.
LGTM but I added one piece of feedback.
nastasha-solomon
added a commit
that referenced
this pull request
Jul 9, 2026
…erimental alerting system (#6522) ## Summary Adds the "Get started" section for the experimental alerting system, contributing to [docs-content-internal#919](elastic/docs-content-internal#919). Following the tech preview principle of accuracy over comprehensiveness, pages focus on stable behavior (e.g., how to enable the system, what privileges are needed, and how to create a first rule) rather than comprehensive feature documentation that is subject to change before GA. Some UI is doc'd in the tutorial, but that's needed for users to follow along. ## Navigation structure ``` Get started ← landing page to be added under top level page for Alerting v2 (#6521) ├── Set up └── Configure access └── Create your first rule ``` ## 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. ### ✏️ Editorial reviewer Focus on writing quality, clarity, and how the content serves a reader enabling and using this feature for the first time. ## Previews — 📁 New v2 content ### Get started | Page name | Description | File | Ready for editorial review ✏️ | Ready for technical review 🔧 | | --------- | ----------- | ---- | ----------------------------- | ----------------------------- | | [Get started](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6522/explore-analyze/alerting/experimental-alerting-system/get-started) | Landing page with per-page summaries linking to setup, access, and the tutorial | explore-analyze/alerting/experimental-alerting-system/get-started.md | ✅ | ✅ | | [Set up the experimental alerting system](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6522/explore-analyze/alerting/experimental-alerting-system/get-started/setup) | Requirements (data, space, connectors, license); `applies-switch` for turning the system on (Serverless only for now) and off; confirmation steps; next steps | explore-analyze/alerting/experimental-alerting-system/get-started/setup.md | ✅ | ✅ | | [Configure access](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6522/explore-analyze/alerting/experimental-alerting-system/get-started/configure-access) | Kibana feature privileges organized by activity; Quick Reference table; bundled ES `read` access via Alerts privilege for `.rule-events`/`.alert-actions`; custom role still required for `.kibana-event-log-*`; Next steps | explore-analyze/alerting/experimental-alerting-system/get-started/configure-access.md | ✅ | ✅ | | [Create your first rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6522/explore-analyze/alerting/experimental-alerting-system/get-started/create-your-first-rule) | Tutorial: Prepare your environment (index + sample data) → Create the rule (5-step stepper) → Confirm the rule is evaluating → Observe the episode lifecycle; requirements table; ES\|QL query explanations for new users | explore-analyze/alerting/experimental-alerting-system/get-started/create-your-first-rule.md | ✅ | ✅ | ## Out of scope for this PR - Rules reference documentation (PR #6523) - Action policies and notifications documentation (PR #6525) - Alerts and Discover query documentation (PR #6527) - Stack/ECH-specific setup behavior (commented out with TODO notes pending 9.5 GA and engineering confirmation for ECH) Cross-references to content in those PRs are present throughout these pages but commented out with TODO notes. > **Note on toc.yml conflicts**: Merge PRs in order and resolve toc.yml conflicts at each step. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes — Cursor + Claude - [ ] No --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Visha Angelova <91186315+vishaangelova@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.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
4 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 rules documentation 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 rules do, when to choose each mode or creation path, and how detection and alerting work — rather than UI step-by-step procedures that are subject to change before GA.
Navigation structure
The rules section is organized into four areas. Reference pages sit at the end of the section so the navigational flow moves from creating a rule to configuring it to managing it, before reaching advanced patterns and field references.
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 rules 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.
Previews - 📁 New v2 content
Section index
Create a rule
Configure a rule
no_data_strategyvalues; when to use each; examplesView and manage rules
ES|QL query patterns
Reference
.rule-eventsdocuments; signal and alert base fields; episode fieldsGenerative AI disclosure