[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages#6523
Draft
nastasha-solomon wants to merge 9 commits into
Draft
[Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages#6523nastasha-solomon wants to merge 9 commits into
nastasha-solomon wants to merge 9 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: 3 warnings, 6 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/rules/configure-a-rule.md | 100 | Elastic.Spelling | 'timeframes' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-experimental/rules/esql-query-patterns.md | 84 | Elastic.DirectionalLanguage | Don't use directional language. Use 'in the preceding element' instead of 'in the example above'. |
| explore-analyze/alerting/kibana-alerting-experimental/rules/rule-event-field-reference.md | 124 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
💡 Suggestions (6): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/rules/author-rules.md | 87 | Elastic.WordChoice | Consider using 'top-level' instead of 'first-class', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-from-rule-builder.md | 35 | Elastic.HeadingColons | Capitalize ': f'. |
| explore-analyze/alerting/kibana-alerting-experimental/rules/view-manage-rules.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/rules/view-manage-rules.md | 33 | 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/rules/view-manage-rules.md | 44 | 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/rules/view-manage-rules.md | 46 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', 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 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>
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
1 participant
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.
Adds ten rules pages under
kibana-alerting-experimental/rules/:rules.md: rules section indexauthor-rules.md,esql-query-patterns.md: authoring guidescreate-rule-from-rule-builder.md,create-rule-from-discover.md,create-rule-with-yaml.md: creation workflowsyaml-rule-schema-reference.md: complete YAML field referenceconfigure-a-rule.md,view-manage-rules.md: management pagesrule-event-field-reference.md:.rule-eventsdocument field reference🤖 Generated with Claude Code