Alert suppression options for missing suppression fields (#3205)

* First (incomplete) draft * tiny edit * Update with latest UI text * Update screenshot * Apply suggestions from Ben's review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
elastic · May 17, 2023 · f4932b5 · f4932b5
1 parent 087d58b
commit f4932b5
Show file tree

Hide file tree

Showing 2 changed files with 5 additions and 1 deletion.
diff --git a/docs/detections/alert-suppression.asciidoc b/docs/detections/alert-suppression.asciidoc
@@ -11,7 +11,7 @@ preview::[]
 
 Alert suppression allows you to reduce the number of repeated or duplicate detection alerts created by a <<create-custom-rule,custom query>> detection rule. 
 
-Normally, when a rule matches multiple source events, it creates multiple alerts, one for each event. When alert suppression is configured, matching events are grouped by a specified field, and only one alert is created for each group. You can configure alert suppression to create alerts each time the rule runs, or once within a specified time window. You can also specify multiple fields to group events by unique combinations of values.
+Normally, when a rule matches multiple source events, it creates multiple alerts, one for each event. When alert suppression is configured, matching events are grouped by their values in a specified field, and only one alert is created for each group. You can configure alert suppression to create alerts each time the rule runs, or once within a specified time window. You can also specify multiple fields to group events by unique combinations of values.
 
 The {security-app} displays several indicators in the Alerts table and the alert details flyout when a detection alert is created with alert suppression enabled. You can view the original events associated with suppressed alerts by investigating the alert in Timeline.
 
@@ -33,6 +33,10 @@ For example, if a rule runs every 5 minutes but you don't need alerts that frequ
 image::images/alert-suppression-options.png[Alert suppression options,400]
 --
 
+. Under *If a suppression field is missing*, choose how to handle events with missing suppression fields (events in which one or more of the *Suppress alerts by* fields don't exist):
+* *Suppress and group alerts for events with missing fields*: Create one alert for each group of events with missing fields. Missing fields get a `null` value, which is used to group and suppress alerts. 
+* *Do not suppress alerts for events with missing fields*: Create a separate alert for each matching event. This basically falls back to normal alert creation for events with missing suppression fields.
+
 . Configure other rule settings, then save and enable the rule.
 
 TIP: Use the *Rule preview* before saving the rule to visualize how alert suppression will affect the alerts created, based on historical data.

diff --git a/docs/detections/images/alert-suppression-options.png b/docs/detections/images/alert-suppression-options.png