[Alerting V2][9.5 & Serverless] Document rule events and how to query signals - #8062
Open
nastasha-solomon wants to merge 22 commits into
Open
[Alerting V2][9.5 & Serverless] Document rule events and how to query signals#8062nastasha-solomon wants to merge 22 commits into
nastasha-solomon wants to merge 22 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: 2 warnings, 2 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/experimental-alerting-system/rules/configure-no-data-handling.md | 13 | Elastic.DontUse | Don't use 'just'. Choose a more precise or reader-focused term. |
| explore-analyze/alerting/experimental-alerting-system/workflows-alerting.md | 13 | Elastic.EndPuntuaction | Don't end headings with punctuation. |
💡 Suggestions (2): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/experimental-alerting-system/action-policies/create-configure-action-policy.md | 69 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI. |
| explore-analyze/alerting/experimental-alerting-system/action-policies/manage-action-policies.md | 23 | 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.
2 tasks
nastasha-solomon
added a commit
that referenced
this pull request
Aug 24, 2026
…nd adjusts wording in docs about rule modes (#7816) ## Summary Adds two flowchart diagrams to the experimental alerting system overview page, visualizing the Alert mode and Signal mode paths as equal outcomes of a rule's mode. Supporting pages get small wording updates so Signal mode isn't described as secondary to Alert mode. The dedicated signals page and the `.rule-events` field reference rename are split into a follow-up PR (#8062) to keep this PR focused on revising the overview page and adding more emphasis on the signals component. Part of elastic/docs-content-internal#1581. ## Previews * [Experimental alerting system overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/system-overview) - Added two flowchart images visualizing Alert mode and Signal mode as equal paths. Revised the core idea, building blocks, and how the pieces fit together so the rule creates the episode or records the signal. Simplified the workflow section to the two invocation paths: action policy, or lifecycle trigger on activation or assignment. **_(main set of changes to review)_** * [Alerting](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting) - Reworded the intro paragraph so it describes choosing between tracked alert episodes and recorded signals, instead of only mentioning alert episode tracking. * [Compare alerting systems](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/compare-alerting-systems) - Split the Experimental alerting system capability row into separate rows: one for what data an alert episode or signal carries, one for recording signals without notifications, and one for querying alert and signal history. Retitled "Alert data" to "Alert and signal data." * [How it works](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/experimental-alerting-system/how-it-works) - Changed the actor from the system to the rule for creating the alert episode (and for making signals queryable). The Alert mode intro now says each match causes the rule to open an episode. * [Rules](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/experimental-alerting-system/rules) - Alert mode now says the rule creates and tracks the episode. Trimmed a redundant clause about testing rules before wiring up notifications. * [Alerts](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/experimental-alerting-system/alerts) - Lifecycle example now says the rule creates the episode in `pending` and does not create extra episodes while one is already `active`. * [Glossary](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/experimental-alerting-system/glossary) - Signal definition now names the `.rule-events` data stream where signals are stored. * [About action policies](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7816/explore-analyze/alerting/experimental-alerting-system/action-policies/about-action-policies) - Reordered a sentence about creating a rule without an action policy and updating notification routing later. No content changes. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No Tool(s) and model(s) used: Cursor (Grok) --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com>
Closed
2 tasks
…signals Treat Signal mode as a first-class outcome: add a query page, a shared rule-event data model, and cross-links from related alerting pages. Co-authored-by: Cursor <cursoragent@cursor.com>
nastasha-solomon
force-pushed
the
alerting-observe-signals
branch
from
August 26, 2026 02:30
adda8f4 to
0690492
Compare
nastasha-solomon
marked this pull request as ready for review
August 26, 2026 03:02
nastasha-solomon
marked this pull request as draft
August 28, 2026 15:21
nastasha-solomon
marked this pull request as ready for review
August 28, 2026 20:07
nastasha-solomon
changed the title
baileycash-elastic
requested changes
Aug 28, 2026
There was a problem hiding this comment.
- I see docs that suggest the user can change "kind" after rule creation. As of today, this is not possible.
- References to "signals" are already somewhat scarce in 9.5, so I would advise against leaning too much into the terminology at this stage with 9.6 so close. Makes me wonder if I should have backported the copy changes.
Member
Author
|
@baileycash-elastic I also scaled back the use of “signals” and “rule mode” terminology across the conceptual pages. They now describe rule events, then either grouping those events into an alert episode or keeping them available for later analysis. This allows the content to stay aligned with the 9.5 behavior, without using soon-to-be-deprecated terms to explain the rule model. Note that the "Rule mode" page does still uses Signal and Alert because that’s the 9.5 UI rule form. cc: @jasonrhodes @tiamliu |
| You're writing a new detection query and want to verify it produces the results you expect before anyone gets paged. Preview the query in the [query sandbox](create-esql-rule.md#rule-builder-query-sandbox) or in Discover, then create the rule in the mode you want to keep. | ||
|
|
||
| You're writing a new detection query and want to verify it produces the results you expect before anyone gets paged. Create the rule in Signal mode so matches are recorded in `.rule-events` and you can inspect them in Discover without opening any alert episodes or triggering notifications. Once the matches look correct, edit the rule and switch it to Alert mode. | ||
| To record matches without opening episodes or triggering notifications, create a rule that records rule events. If you later want those matches tracked as episodes, create a separate rule that groups them into an episode. You can reuse the same query, or write a follow-on query that reads those events from `.rule-events`. For the follow-on pattern, refer to [Correlate events in a follow-on rule](../alerts/query-signals.md#correlate-signals-alert-rule). |
There was a problem hiding this comment.
Suggested change
| To record matches without opening episodes or triggering notifications, create a rule that records rule events. If you later want those matches tracked as episodes, create a separate rule that groups them into an episode. You can reuse the same query, or write a follow-on query that reads those events from `.rule-events`. For the follow-on pattern, refer to [Correlate events in a follow-on rule](../alerts/query-signals.md#correlate-signals-alert-rule). | |
| To record matches without opening episodes or triggering notifications, create a rule with (`type: alert`). If you later want those matches tracked as episodes, create a separate rule that groups them into an episode. You can reuse the same query, or write a follow-on query that reads those events from `.rule-events`. For the follow-on pattern, refer to [Correlate events in a follow-on rule](../alerts/query-signals.md#correlate-signals-alert-rule). |
Member
Author
There was a problem hiding this comment.
Wouldn't a rule of type:alert generate alert episodes?
| @@ -0,0 +1,103 @@ | |||
| --- | |||
| navigation_title: Query signals | |||
There was a problem hiding this comment.
this is where I want to press hard on the use of signal terminology. If this is published and later we change ui terminology to events, will this be confusing from a docs nav perspective?
Member
Author
There was a problem hiding this comment.
Can you elaborate on your concern? In this PR, the "signals" has been removed from the majority of the alerting v2 docs, so this changing to "events" on this specific page and accompanied by an explanatory note shouldn't be a major paradigm shift.
There was a problem hiding this comment.
If you plan on offering a note/callout for the change in terminology then I think that covers it 👍
| - **Catch unexpected output** - Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule. | ||
| - **Refine before committing** - Edit the query and re-run it as many times as needed without leaving the rule creation form. | ||
|
|
||
| While the sandbox is open, switching between rule form and YAML or between rule modes (Alert and Signal) is not available. Close the sandbox first if you need to change authoring mode. |
Member
Author
There was a problem hiding this comment.
Since the deleted version could be mis-interpreted as supporting rule mode switching, what revision would be more accurate?
There was a problem hiding this comment.
Ah ok. Technically you can switch in create mode but if we're trying to reduce confusion by not describing it at all that's fine
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
2 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
Fixes https://github.com/elastic/docs-content-internal/issues/1581.
Fixes #8088.
The 9.5 docs treated rule mode as the fork: a match either became an alert episode or a signal. That made signals look like a second kind of output, and there were no docs for how to query them. This PR fixes that gap and also documents what actually happens: Kibana writes a rule event to
.rule-events, then the rule’s configuration groups that event into an episode or leaves it for later analysis. That is more precise for 9.5, and it lets the conceptual pages skip rule mode so they won’t need a heavy rewrite for the 9.6 and Serverless UI changes described in in #8085.What's excluded: 9.6 and Serverless authoring changes stay in a follow-up PR. Note that the Rule mode page still uses "Signal" and "Alert" because those are the 9.5 UI labels. This keeps the conceptual pages stable across the 9.5 → 9.6 transition without relying on terms that may change.
What's needed from PM, eng, and or UX: If "rule mode," "Alert mode," "Signal mode," and "signal" are being retired as user-facing terms, what are the replacement terms and the replacement mental model for users? I haven't been able to find a formal decision recorded in the rna-program repo, #8085, or the relevant Slack channels.
This PR is interim solution, while those decisions are being finalized. The conceptual pages now describe system behavior in terms of rule events. Rule events are either grouped into an episode or remain available for later analysis. If the team has a different replacement model in mind, please share that here or add it to the program repo so I can apply it consistently across these docs.
Previews
New pages
.rule-eventsfor each match, and how Signal mode and Alert mode use it..rule-events.Conceptual rewrites
episode.id, and routes notifications through an action policy.type: signalortype: alert.Wording and links
no_dataevents..rule-eventsas one event per matching row, per run.Generative AI disclosure