diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 5f13c6e1774a8..77a4e5cc41ef2 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -59,7 +59,7 @@ image::images/alert-flyout-action-type-selection.png[UI for selecting an action When an alert instance matches a condition, the alert is marked as _Active_ and assigned an action group. The actions in that group are triggered. When the condition is no longer detected, the alert is assigned to the _Recovered_ action group, which triggers any actions assigned to that group. -**Run When** allows you to assign an action to an _action group_. This will trigger the action in accordance with your **Notify every** setting. +**Run When** allows you to assign an action to an action group. This will trigger the action in accordance with your **Notify** setting. Each action must specify a <> instance. If no connectors exist for that action type, click *Add action* to create one. @@ -68,7 +68,20 @@ Each action type exposes different properties. For example an email action allow [role="screenshot"] image::images/alert-flyout-action-details.png[UI for defining an email action] -Using the https://mustache.github.io/[Mustache] template syntax `{{variable name}}`, you can pass alert values at the time a condition is detected to an action. Available variables differ by alert type, and the list of available variables can be accessed using the "add variable" button. +[float] +==== Action variables +Using the https://mustache.github.io/[Mustache] template syntax `{{variable name}}`, you can pass alert values at the time a condition is detected to an action. You can access the list of available variables using the "add variable" button. Although available variables differ by alert type, all alert types pass the following variables: + +`alertId`:: The ID of the alert. +`alertName`:: The name of the alert. +`spaceId`:: The ID of the space for the alert. +`tags`:: The list of tags applied to the alert. +`date`:: The date the alert scheduled the action, in ISO format. +`alertInstanceId`:: The ID of the alert instance that scheduled the action. +`alertActionGroup`:: The ID of the action group of the alert instance that scheduled the action. +`alertActionSubgroup`:: The action subgroup of the alert instance that scheduled the action. +`alertActionGroupName`:: The name of the action group of the alert instance that scheduled the action. +`kibanaBaseUrl`:: The configured <>. If not configured, this will be empty. [role="screenshot"] image::images/alert-flyout-action-variables.png[Passing alert values to an action] diff --git a/docs/user/alerting/images/alert-types-es-query-example-action-variable.png b/docs/user/alerting/images/alert-types-es-query-example-action-variable.png new file mode 100644 index 0000000000000..7e40499d78fdd Binary files /dev/null and b/docs/user/alerting/images/alert-types-es-query-example-action-variable.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-conditions.png b/docs/user/alerting/images/alert-types-index-threshold-conditions.png index 5d66123ac733e..062b0a426b5d8 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-conditions.png and b/docs/user/alerting/images/alert-types-index-threshold-conditions.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-aggregation.png b/docs/user/alerting/images/alert-types-index-threshold-example-aggregation.png index 055b643ec3458..a43c4bf1f0d37 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-aggregation.png and b/docs/user/alerting/images/alert-types-index-threshold-example-aggregation.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-grouping.png b/docs/user/alerting/images/alert-types-index-threshold-example-grouping.png index 5be81b45612bc..9f4c2ccbec3c0 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-grouping.png and b/docs/user/alerting/images/alert-types-index-threshold-example-grouping.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-index.png b/docs/user/alerting/images/alert-types-index-threshold-example-index.png index b13201ce5d38a..b2f1c78f7add8 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-index.png and b/docs/user/alerting/images/alert-types-index-threshold-example-index.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-preview.png b/docs/user/alerting/images/alert-types-index-threshold-example-preview.png index 70e1355004c47..19ad52c45da1c 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-preview.png and b/docs/user/alerting/images/alert-types-index-threshold-example-preview.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-threshold.png b/docs/user/alerting/images/alert-types-index-threshold-example-threshold.png index 7e9432d8c8678..9d9262dd96a1e 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-threshold.png and b/docs/user/alerting/images/alert-types-index-threshold-example-threshold.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-timefield.png b/docs/user/alerting/images/alert-types-index-threshold-example-timefield.png index 4b1eaa631dc98..e7b13ed6e2cc0 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-timefield.png and b/docs/user/alerting/images/alert-types-index-threshold-example-timefield.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-example-window.png b/docs/user/alerting/images/alert-types-index-threshold-example-window.png index b4b272d2a241a..9b8e9a47ae91e 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-example-window.png and b/docs/user/alerting/images/alert-types-index-threshold-example-window.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-preview.png b/docs/user/alerting/images/alert-types-index-threshold-preview.png index b3b868dbc41e8..2065cbd117b75 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-preview.png and b/docs/user/alerting/images/alert-types-index-threshold-preview.png differ diff --git a/docs/user/alerting/images/alert-types-index-threshold-select.png b/docs/user/alerting/images/alert-types-index-threshold-select.png index 18c28a703e966..7a68d8815b6d9 100644 Binary files a/docs/user/alerting/images/alert-types-index-threshold-select.png and b/docs/user/alerting/images/alert-types-index-threshold-select.png differ diff --git a/docs/user/alerting/stack-alerts/es-query.asciidoc b/docs/user/alerting/stack-alerts/es-query.asciidoc index 772178c9552da..9f4a882328b9f 100644 --- a/docs/user/alerting/stack-alerts/es-query.asciidoc +++ b/docs/user/alerting/stack-alerts/es-query.asciidoc @@ -28,6 +28,27 @@ condition. Aggregations are not supported at this time. Threshold:: This clause defines a threshold value and a comparison operator (`is above`, `is above or equals`, `is below`, `is below or equals`, or `is between`). The number of documents that match the specified query is compared to this threshold. Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be set to a value higher than the *check every* value in the <>, to avoid gaps in detection. +[float] +==== Action variables + +When the ES query alert condition is met, the following variables are available to use inside each action: + +`context.title`:: A preconstructed title for the alert. Example: `alert term match alert query matched`. +`context.message`:: A preconstructed message for the alert. Example: + +`alert 'term match alert' is active:` + +`- Value: 42` + +`- Conditions Met: count greater than 4 over 5m` + +`- Timestamp: 2020-01-01T00:00:00.000Z` + +`context.group`:: The name of the action group associated with the condition. Example: `query matched`. +`context.date`:: The date, in ISO format, that the alert met the condition. Example: `2020-01-01T00:00:00.000Z`. +`context.value`:: The value of the alert that met the condition. +`context.conditions`:: A description of the condition. Example: `count greater than 4`. +`context.hits`:: The most recent ES documents that matched the query. Using the https://mustache.github.io/[Mustache] template array syntax, you can iterate over these hits to get values from the ES documents into your actions. + +[role="screenshot"] +image::images/alert-types-es-query-example-action-variable.png[Iterate over hits using Mustache template syntax] + [float] ==== Testing your query diff --git a/docs/user/alerting/stack-alerts/index-threshold.asciidoc b/docs/user/alerting/stack-alerts/index-threshold.asciidoc index 424320aea3adc..6b45f69401c4a 100644 --- a/docs/user/alerting/stack-alerts/index-threshold.asciidoc +++ b/docs/user/alerting/stack-alerts/index-threshold.asciidoc @@ -31,6 +31,23 @@ If data is available and all clauses have been defined, a preview chart will ren [role="screenshot"] image::user/alerting/images/alert-types-index-threshold-preview.png[Five clauses define the condition to detect] +[float] +==== Action variables + +When the index threshold alert condition is met, the following variables are available to use inside each action: + +`context.title`:: A preconstructed title for the alert. Example: `alert kibana sites - high egress met threshold`. +`context.message`:: A preconstructed message for the alert. Example: + +`alert 'kibana sites - high egress' is active for group 'threshold met':` + +`- Value: 42` + +`- Conditions Met: count greater than 4 over 5m` + +`- Timestamp: 2020-01-01T00:00:00.000Z` + +`context.group`:: The name of the action group associated with the threshold condition. Example: `threshold met`. +`context.date`:: The date, in ISO format, that the alert met the threshold condition. Example: `2020-01-01T00:00:00.000Z`. +`context.value`:: The value for the alert that met the threshold condition. +`context.conditions`:: A description of the threshold condition. Example: `count greater than 4` + [float] ==== Example