a7c9d3f1e0
* Renaming alerts to rules * Updating formatted messages * Updating i18n labels * Completed renaming in UI * Updating client routes including redirect * wip docs update * Reverting title changes for now * Fixing types check * Fixing unit tests * Fixing functional test * Fixing functional test * docs wip * wip docs update * Finished first run through docs * docs docs docs * Fixing bad merge * Fixing functional test * Docs cleanup * Cleaning up i18n labels * Fixing functional test * Updating screenshots * Updating screenshots * Updating screenshots * Updating terminology in alerting examples * Updating terminology in alerting examples Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
63 lines
3.4 KiB
Plaintext
63 lines
3.4 KiB
Plaintext
[role="xpack"]
|
|
[[rule-type-es-query]]
|
|
=== {es} query
|
|
|
|
The {es} query rule type runs a user-configured {es} query, compares the number of matches to a configured threshold, and schedules actions to run when the threshold condition is met.
|
|
|
|
[float]
|
|
==== Create the rule
|
|
|
|
Fill in the <<defining-alerts-general-details, rule details>>, then select *{es} query*.
|
|
|
|
[float]
|
|
==== Define the conditions
|
|
|
|
Define properties to detect the condition.
|
|
|
|
[role="screenshot"]
|
|
image::user/alerting/images/rule-types-es-query-conditions.png[Five clauses define the condition to detect]
|
|
|
|
Index:: This clause requires an *index or index pattern* and a *time field* that will be used for the *time window*.
|
|
Size:: This clause specifies the number of documents to pass to the configured actions when the the threshold condition is met.
|
|
{es} query:: This clause specifies the ES DSL query to execute. The number of documents that match this query will be evaulated against the threshold
|
|
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 rule details>>, to avoid gaps in detection.
|
|
|
|
[float]
|
|
==== Add action variables
|
|
|
|
<<defining-alerts-actions-details, Add an action>> to run when the rule condition is met. The following variables are specific to the {es} query rule. You can also specify <<defining-alerts-actions-variables, variables common to all rules>>.
|
|
|
|
`context.title`:: A preconstructed title for the rule. Example: `rule term match alert query matched`.
|
|
`context.message`:: A preconstructed message for the rule. Example: +
|
|
`rule '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 rule met the condition. Example: `2020-01-01T00:00:00.000Z`.
|
|
`context.value`:: The value of the rule 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/rule-types-es-query-example-action-variable.png[Iterate over hits using Mustache template syntax]
|
|
|
|
|
|
[float]
|
|
==== Test your query
|
|
|
|
Use the *Test query* feature to verify that your query DSL is valid.
|
|
|
|
* Valid queries are executed against the configured *index* using the configured *time window*. The number of documents that
|
|
match the query will be displayed.
|
|
+
|
|
[role="screenshot"]
|
|
image::user/alerting/images/rule-types-es-query-valid.png[Test {es} query returns number of matches when valid]
|
|
|
|
* An error message is shown if the query is invalid.
|
|
+
|
|
[role="screenshot"]
|
|
image::user/alerting/images/rule-types-es-query-invalid.png[Test {es} query shows error when invalid] |