[Alerting V2][Serverless & 9.5][M2] Rule changes from June 22, 2026

[nastasha-solomon]

Summary

Updates rules docs for the experimental alerting system with content from nine M2 doc issues and one additional issue (#7092). Following the tech preview principle of accuracy over comprehensiveness, additions focus on stable concepts — why to choose certain options, when to use features, and how the system works. UI step-by-step procedures, unstable IA details, and incomplete API schemas are deferred to post-preview docs.

ES|QL rule base + blocks query schema and ?param placeholder syntax (#7004)

PR #271758 introduced a structured API and saved-object schema for ES|QL rules comprising a base query and optional blocks.

author-rules.md — Added a Query parameters subsection to the ES|QL query section documenting ?param placeholder syntax. Includes a code example showing a parameterized threshold condition. The exact mechanism for supplying parameter values (rule form, API, or YAML params key), supported types, and validation behavior are deferred — a TODO comment tracks this for follow-up once the M2 parameterization API is finalized.

yaml-rule-schema-reference.md — Added evaluation.query.blocks to the required fields table with a description of how blocks extend the base query. A TODO comment asks to confirm the exact accepted structure (bare clause vs. full expression, maximum count, maximum length) against the M2 schema before publishing.

Alert delay field in the Threshold Alert rule builder (#7008)

PR #273501 added an alert delay field to the threshold rule builder inside the rule form flyout. The field supports three modes — Immediate, Breaches, and Duration — and is only visible in Alert mode.

configure-a-rule.md — Replaced the bare field table in the activation thresholds section with a mode table (Immediate, Breaches, Duration) that explains what each mode does and when to use it. Added a concrete example for combining Breaches and Duration with AND/OR. Updated field descriptions to be self-contained and behavior-focused. Folded the timeframe bounds note into the table lead-in to remove the floating afterthought at the end of the section.

create-rule-from-rule-builder.md — Added an Alert delay subsection to the Threshold Alert section. It references configure-a-rule.md for the full mode descriptions rather than duplicating them, and notes that the field is absent for Signal-mode rules because signals don't maintain alert episode lifecycle tracking.

Alert activity timeline on the rule details page (#6874)

PR #267866 added an alert activity timeline widget to the rule details overview tab, including color-coded per-series lanes, summary stats, a "View all episodes" link, and clickable segments that open episode detail pages.

view-manage-rules.md — Updated the Rule details page section to document the Overview tab. Covers the timeline's per-series state history, summary statistics (alert episodes started, recovered, still open, median duration), the filtered "View all episodes" link, and the behavior difference between grouped and ungrouped rules. Notes that the Overview tab is not shown for Signal-mode rules.

Query preview tab in the rule summary flyout (#7007)

PR #270484 added a query preview tab to the rule attachment sidebar, restricted to Agent Builder rule types.

view-manage-rules.md — Updated the Rule summary flyout section to note that the flyout includes a query preview tab for AI Agent builder rules. The tab renders the rule's underlying ES|QL in an interactive sandbox. Structured as two sentences to avoid em dashes for the restriction qualifier.

YAML-only mode for non-representable rule configurations (#7092)

PR #274207 changed the rule edit flyout to force YAML-only mode and disable the Form/YAML toggle when a rule's configuration contains settings the form cannot represent. Previously, opening such rules in the UI would silently drop the unrepresentable fields on save.

create-rule-from-rule-builder.md — Updated the form/YAML editing section to scope "switch between them at any point" to new rule creation only. Added a paragraph explaining that on edit, the toggle is disabled for non-representable configurations, why this happens (prevents silent data loss), and linking to the full list in create-rule-with-yaml.md.

create-rule-with-yaml.md — Added a "YAML-only mode when editing rules" section with a table of the four configurations that force YAML-only mode (query.format: standalone with kind: alert, recovery_strategy: no_breach or none, no_data_strategy, query.no_data block), an explanation of why each is non-representable, and a recovery path for users who want to switch back to form editing. A TODO comment flags a discrepancy between the field names in the issue and the currently documented YAML schema fields (recovery_policy.type, no_data.behavior) for verification against the shipped M2 schema.

Page scope statements added to all rules pages

Each page in the rules set now has an explicit "This page covers..." sentence in its opening paragraph, following the naming cheat sheet guidance. Applied to: rules.md, configure-a-rule.md, view-manage-rules.md, create-rule-from-rule-builder.md, create-rule-from-discover.md, create-rule-with-yaml.md, and esql-query-patterns.md. The three pages that already had clear scope statements (author-rules.md, rule-event-field-reference.md, yaml-rule-schema-reference.md) were not changed.

Issues confirmed as already covered or out of scope

• [Alerting V2] [DOCS] [M2] Rule kind label renamed from "Detection only" to "Signal" #6837 (Signal label renamed from "Detection only"): docs already use "Signal". No changes needed.
• [Alerting V2] [DOCS] [M2] Choose between Alert and Signal mode when creating an Alerting v2 rule #6870 (Alert/Signal mode select replaces toggle): Alert and Signal modes are already documented in author-rules.md and configure-a-rule.md. UI control details are deferred.
• [Alerting V2] [DOCS] [M2] Alerting v2 rules list: empty state and getting started options #6875 (Rules list empty state redesign): the three creation paths in rules.md already match the redesigned empty state panels. No changes needed.
• [Alerting V2] [DOCS] [M2] Add simple alert actions from the Alerting v2 rule form #7005 (Simple actions from rule form): already covered by the existing note at the top of configure-a-rule.md. No changes needed.
• [Alerting V2] [DOCS] [M2] Navigate to Alerting v2 rules management from the alert episodes list #6871 (Manage rules button on the episodes list): this is a navigation element on the episodes list page, not the rules docs. Out of scope for this PR.
• [Alerting V2] [DOCS] [M2] Query sandbox preview opens automatically when creating a new alerting v2 rule #7015 (Query sandbox auto-opens on create): this is a UI behavior detail about flyout initialization state, not a stable concept. Deferred to post-preview step-by-step procedure docs.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes - Cursor + Claude
• No

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.