Skip to content

Commit

Permalink
[DOCS] Clarify support for data views in stack rules (elastic#158431)
Browse files Browse the repository at this point in the history
(cherry picked from commit 4981f37)
  • Loading branch information
lcawl committed May 25, 2023
1 parent de87c14 commit ad48a07
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 15 deletions.
27 changes: 17 additions & 10 deletions docs/user/alerting/rule-types/es-query.asciidoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
[[rule-type-es-query]]
== {es} query

:frontmatter-description: An {es} query rule generates alerts when your query meets a threshold.
:frontmatter-tags-products: [kibana,alerting]
:frontmatter-tags-content-type: [overview]
:frontmatter-tags-user-goals: [analyze]

The {es} query rule type runs a user-configured query, compares the number of
matches to a configured threshold, and schedules actions to run when the
threshold condition is met.
Expand All @@ -20,19 +25,21 @@ Define properties to detect the condition.
[role="screenshot"]
image::user/alerting/images/rule-types-es-query-conditions.png[Eight clauses define the condition to detect]

Index:: Specifies an *index or data view* and a *time field* that is used for
the *time window*.
{es} query:: Specifies the ES DSL query. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered.
When:: Specifies how the value to be compared to the threshold is calculated. The value is calculated by aggregating a numeric field within the *time window*. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used and an aggregation field is not necessary.
Over or Grouped Over:: Specifies whether the aggregation is applied over all documents or split into groups using a grouping field. If grouping is used, an <<alerting-concepts-alerts,alert>> will be created for each group when it meets the condition. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the *top* groups are checked.
Threshold:: Defines a threshold value and a comparison operator (`is above`,
Define your query::
If you chose the query DSL option, you must specify indices to query and a time field that is used for the time window. You must then define a query in {es} query DSL. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered.
+
If you chose the KQL or Lucene option, you must specify a data view then define a text-based query.
Set the group, theshold, and time window::
When::: Specify how to calculate the value that is compared to the threshold. The value is calculated by aggregating a numeric field within the time window. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used and an aggregation field is not necessary.
Over or Grouped Over::: Specify whether the aggregation is applied over all documents or split into groups using a grouping field. If grouping is used, an alert will be created for each group when it meets the condition. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the top groups are checked.
Threshold::: Defines a threshold value and a comparison operator (`is above`,
`is above or equals`, `is below`, `is below or equals`, or `is between`). The value
calculated by the aggregation is compared to this threshold.
Time window:: Defines 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, to avoid gaps in
Time window::: Defines 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 interval, to avoid gaps in
detection.
Size:: Specifies the number of documents to pass to the configured actions when
Set the number of documents to send:: Specifies the number of documents to pass to the configured actions when
the threshold condition is met.
Exclude matches from previous run:: Turn on to avoid alert duplication by
excluding documents that have already been detected by the previous rule run. This
Expand Down
17 changes: 12 additions & 5 deletions docs/user/alerting/rule-types/index-threshold.asciidoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
[[rule-type-index-threshold]]
== Index threshold

:frontmatter-description: An index threshold rule generates alerts when an aggregated query meets a threshold.
:frontmatter-tags-products: [kibana,alerting]
:frontmatter-tags-content-type: [overview]
:frontmatter-tags-user-goals: [analyze]

The index threshold rule type runs an {es} query. It aggregates field values from documents, compares them to threshold values, and schedules actions to run when the thresholds are met.

[float]
Expand All @@ -12,11 +17,13 @@ image::user/alerting/images/rule-types-index-threshold-conditions.png[Defining i

When you create an index threshold rule, you must define the conditions for the rule to detect. For example:

Index:: This clause requires an *index or data view* and a *time field* that will be used for the *time window*.
When:: This clause specifies how the value to be compared to the threshold is calculated. The value is calculated by aggregating a numeric field a the *time window*. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used, and an aggregation field is not necessary.
Over/Grouped Over:: This clause lets you configure whether the aggregation is applied over all documents, or should be split into groups using a grouping field. If grouping is used, an <<alerting-concepts-alerts, alert>> will be created for each group when it exceeds the threshold. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the *top* groups are checked.
Threshold:: This clause defines a threshold value and a comparison operator (one of `is above`, `is above or equals`, `is below`, `is below or equals`, or `is between`). The result of the aggregation 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 to a value higher than the *check every* value, to avoid gaps in detection.
Select an index::
Index::: Specify the indices to query and a time field that will be used for the time window.
When::: Specify how to calculate the value that is compared to the threshold. The value is calculated by aggregating a numeric field in a time window. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used and an aggregation field is not necessary.
Over/Grouped Over::: Specify whether the aggregation is applied over all documents or split into groups using a grouping field. If grouping is used, an <<alerting-concepts-alerts,alert>> will be created for each group when it exceeds the threshold. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the top groups are checked.
Define the condition::
This section defines a threshold value and a comparison operator (`is above`, `is above or equals`, `is below`, `is below or equals`, or `is between`). The result of the aggregation is compared to this threshold.
It also defines a time window, which determines how far back to search for documents, using the time field set in the index clause. Generally this value should be a value higher than the check interval to avoid gaps in detection.

If data is available and all clauses have been defined, a preview chart will render the threshold value and display a line chart showing the value for the last 30 intervals. This can provide an indication of recent values and their proximity to the threshold, and help you tune the clauses.

Expand Down

0 comments on commit ad48a07

Please sign in to comment.