elastic / elastic/docs-content

[Alerting V2] Update Rule Authoring Docs

Open
#8,085 3 comments 0 reactions 1 assignee Claimed by @nastasha-solomon View on GitHub
alerting-v2 Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

### Description

We're refining the rule authoring experience, following stakeholder feedback on the differences between alert and signal rules.
- Query definition is first in the authoring flow. Users can define a query as they see fit. If they want to split their query to visualize base vs alert condition, this is still available, but not the default. Splitting the query (into two tabs) has moved into a settings menu within the sandbox.
- Rule kind selection is now in a separate step. Previously, this was referred to as "mode" in the GUI (list and form). Now, we refer to it as "outcome" in those places. The underlying value in the saved object, API, and YAML form will continue to be "kind."
- Why "outcome?" Outcome better summarizes what the user may want to do with the rule, not what the rule itself produces. Outcomes are described in the UI as "Detect and respond" (create alerts/episodes) and "Collect evidence" (create logs/events only)
- We're removing references to "signal" in the GUI. Signals point to the same document source as alert rule events (`.rule-events`), so it can be confusing to suggest that these are different from rule events generated by alert rules. Alert rules produce episodes from rule events, while "signal" rules ... only produce rule events. Signals are not a separate structure, so we don't need to add confusion in the GUI by throwing in this term. Instead, we'll just use "events."
- Alert recovery is no longer in a dedicated step. It will be configurable below the outcome selection. It appears by default if the user leaves the selected "outcome" as "detect and respond." If they change the outcome to "collect evidence," recovery goes away. This specific behavior is unchanged, but now fields go away in the same view, not on a separate step.

### Resources

https://github.com/elastic/kibana/pull/283528 - Restructure
https://github.com/elastic/kibana/pull/284737 - Terminology changes to signal, becoming "events"
https://github.com/elastic/kibana/pull/286633 - Cleanup

### Which deployment methods does this change impact?

Elastic On-Prem and Cloud (all)

### Feature differences

_No response_

### What Elastic Stack release is this request related to?

9.6

### Serverless release

Already released, week of 25 Aug

### Collaboration model

The documentation team will create the first draft

### Point of contact.

**Main contact:** @baileycash-elastic

**Stakeholders:** @tiamliu

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.