elastic / elastic/docs-content
[Alerting V2] [M2] Explain rule events and connect them to alert episodes and signals
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 21h
- Merged PRs (30d)
- 141
Description
### Description
What: Rule events in the experimental alerting system (Alerting V2) need a plain-language explanation, and they need to be connected to the Alert mode and Signal mode flows. Today the docs treat signals and alert episodes as if they were the documents Kibana writes. They are not. Kibana writes a rule event to `.rule-events` when a rule finds a match (one event per matching row, per run). It never overwrites those events. In Signal mode, that event is the whole output (`type: signal`). In Alert mode, the event is `type: alert` and carries `episode.*` fields. An alert episode is the grouping of those events that share an `episode.id`, not a separate document type.
Pages to update:
- Canonical explanation: Rule events (`rules/rule-event-field-reference.md`)
- Overview, How it works, Rules, Alerts, glossary, Observe and analyze signals, Rule event data model, Field reference
Write this in the same voice as the rest of the experimental alerting docs. Do not paste the program-repo glossary wording. Keep the public field name `type` on `.rule-events` documents (`signal` | `alert`). The rule object uses `kind`; that is a different field.
When: Experimental in Elastic Stack 9.5+ and Serverless. This is a docs-clarity follow-up, not a new product feature.
Why: Users can’t follow the system if rule events, signals, and alert episodes are conflated. Making the rule event the shared starting point for both modes makes the rest of the docs coherent.
### Resources
Internal definition: `docs/glossary/v2.md` in the alerting program repo. A rule event is the immutable document produced when a rule executes and its criteria match: one event per result row, per execution; never updated in place.
Canonical Kibana schema (source of truth for field names): `x-pack/platform/plugins/shared/alerting_v2/server/resources/datastreams/alert_events.ts` on 9.5. Event documents use `type` (`signal` | `alert`). Rule YAML/saved objects use `kind` (`alert` | `signal`). Do not rename `type` to `kind` in public docs (docs-content-internal#1685 is incorrect against Kibana).
### Which deployment methods does this change impact?
Elastic On-Prem and Cloud (all)
### Feature differences
The feature is identical in all deployment methods where experimental alerting is available: Elastic Stack 9.5+ (experimental) and Serverless (experimental).
### What Elastic Stack release is this request related to?
9.5
### Serverless release
Already available as experimental in Serverless. No GA promotion date for this docs change.
### Collaboration model
The documentation team will create the first draft
### Point of contact.
RnA progam team
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.