[Alerting][Docs] Documentation for action variables. (#92417)

* Adding action variable docs for index threshold and ES query alerts

* Adding section for common action variables

* Adding link to server publicBaseUrl

* PR fixes
This commit is contained in:
ymao1 2021-02-24 12:55:22 -05:00 committed by GitHub
parent bd0eed4f23
commit e78d5f6d04
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 53 additions and 2 deletions

View file

@ -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 <<alerting-concepts-connectors, connector>> 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 <<server-publicBaseUrl, `server.publicBaseUrl`>>. If not configured, this will be empty.
[role="screenshot"]
image::images/alert-flyout-action-variables.png[Passing alert values to an action]

Binary file not shown.

After

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 75 KiB

After

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 82 KiB

After

Width:  |  Height:  |  Size: 114 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 138 KiB

After

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 196 KiB

After

Width:  |  Height:  |  Size: 177 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 98 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 140 KiB

After

Width:  |  Height:  |  Size: 171 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 100 KiB

After

Width:  |  Height:  |  Size: 121 KiB

View file

@ -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 <<defining-alerts-general-details, general alert details>>, 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

View file

@ -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