You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[9.1 & Serverless][ResponseOps] ES|QL rule type ungrouped alerts (elastic#2015)
## Summary
Contributes to elastic#1714.
In this PR, I made a couple of changes:
- Documented alert grouping options for the Elasticsearch query rules in
Kibana (Stack Management) and Observability.
- Added `applies to` tags (Serverless and Stack) to the "Create an
Elasticsearch query rule" page in the Observability docs.
**Corresponding 8.19 docs**
- Kibana: elastic/kibana#226315
## Preview
[Here](elastic#2015 (comment))
---------
Co-authored-by: Mike Birnstiehl <[email protected]>
Copy file name to clipboardExpand all lines: explore-analyze/alerts-cases/alerts/rule-type-es-query.md
+32-21Lines changed: 32 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ When you create an {{es}} query rule, your choice of query type affects the info
26
26
27
27
1. Define your query
28
28
29
-
If you use [query DSL](../../query-filter/languages/querydsl.md), you must select an index and time field then provide your query. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered. For example:
29
+
*If you use [query DSL](../../query-filter/languages/querydsl.md), you must select an index and time field then provide your query. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered. For example:
30
30
31
31
```sh
32
32
{
@@ -36,34 +36,45 @@ When you create an {{es}} query rule, your choice of query type affects the info
36
36
}
37
37
```
38
38
39
-
If you use [KQL](../../query-filter/languages/kql.md) or [Lucene](../../query-filter/languages/lucene-query-syntax.md), you must specify a data view then define a text-based query. For example, `http.request.referrer: "https://example.com"`.
39
+
*If you use [KQL](../../query-filter/languages/kql.md) or [Lucene](../../query-filter/languages/lucene-query-syntax.md), you must specify a data view then define a text-based query. For example, `http.request.referrer: "https://example.com"`.
40
40
41
-
If you use [ES|QL](../../query-filter/languages/esql.md), you must provide a sourcecommand followed by an optional series of processing commands, separated by pipe characters (|).
41
+
* If you use [ES|QL](../../query-filter/languages/esql.md), you must provide a sourcecommand followed by an optional series of processing commands, separated by pipe characters (|).
42
42
43
-
:::{admonition} Added in 8.16.0
44
-
This functionality was added in 8.16.0.
45
-
:::
43
+
:::{admonition} Added in 8.16.0
44
+
This functionality was added in 8.16.0.
45
+
:::
46
46
47
-
For example:
47
+
For example:
48
48
49
-
```sh
50
-
FROM kibana_sample_data_logs
51
-
| STATS total_bytes = SUM(bytes) BY host
52
-
| WHERE total_bytes > 200000
53
-
| SORT total_bytes DESC
54
-
| LIMIT 10
55
-
```
49
+
```sh
50
+
FROM kibana_sample_data_logs
51
+
| STATS total_bytes = SUM(bytes) BY host
52
+
| WHERE total_bytes > 200000
53
+
| SORT total_bytes DESC
54
+
| LIMIT 10
55
+
```
56
+
57
+
2. Specify details for grouping alerts based on your query language.
58
+
59
+
* If you use query DSL, KQL, or Lucene, set the group and theshold.
60
+
61
+
When
62
+
: 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.
63
+
64
+
Over or Grouped Over
65
+
: Specify whether the aggregation is applied over all documents or split into groups using up to four grouping fields. If you choose to use grouping, it’s a [terms](elasticsearch://reference/aggregations/search-aggregations-bucket-terms-aggregation.md) or [multi terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-multi-terms-aggregation.md); an alert will be created for each unique set of values 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.
56
66
57
-
2. If you use query DSL, KQL, or Lucene, set the group and theshold.
67
+
Threshold
68
+
: 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.
58
69
59
-
When
60
-
: 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.
70
+
* {applies_to}`stack: ga 9.2` If you use {{esql}}, specify a time field and how to group alerts.
61
71
62
-
Over or Grouped Over
63
-
:Specify whether the aggregation is applied over all documents or split into groups using up to four grouping fields. If you choose to use grouping, it’s a [terms](elasticsearch://reference/aggregations/search-aggregations-bucket-terms-aggregation.md) or [multi terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-multi-terms-aggregation.md); an alert will be created foreach unique set of values 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.
72
+
Time field
73
+
: Choose the time field to use when filtering query results by the time window that you later specify for the rule. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field.
64
74
65
-
Threshold
66
-
: 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.
75
+
Alert group
76
+
: Select **Create an alert if matches are found** to create a single alert for multiple events matching the {{esql}} query. Select **Create an alert for each row** to create a separate alert for each event that matches the {{esql}} query. Whenever possible, each alert is given a unique ID.
77
+
67
78
68
79
3. Set the time window, which defines how far back to search for documents.
69
80
4. If you use query DSL, KQL, or Lucene, set the number of documents to send to the configured actions when the threshold condition is met.
@@ -38,38 +41,50 @@ When you create an {{es}} query rule, your choice of query type affects the info
38
41
39
42
1. Define your query
40
43
41
-
If you use [query DSL](/explore-analyze/query-filter/languages/querydsl.md), you must select an index and time field then provide your query. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered. For example:
44
+
*If you use [query DSL](../../../explore-analyze/query-filter/languages/querydsl.md), you must select an index and time field then provide your query. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered. For example:
42
45
43
46
```sh
44
47
{
45
-
"query":{
46
-
"match_all": {}
47
-
}
48
-
}
48
+
"query":{
49
+
"match_all": {}
50
+
}
51
+
}
49
52
```
50
53
51
-
If you use [KQL](/explore-analyze/query-filter/languages/kql.md) or [Lucene](/explore-analyze/query-filter/languages/lucene-query-syntax.md), you must specify a data view then define a text-based query. For example, `http.request.referrer: "https://example.com"`.
54
+
*If you use [KQL](../../../explore-analyze/query-filter/languages/kql.md) or [Lucene](../../../explore-analyze/query-filter/languages/lucene-query-syntax.md), you must specify a data view then define a text-based query. For example, `http.request.referrer: "https://example.com"`.
52
55
53
-
If you use [ES|QL](/explore-analyze/query-filter/languages/esql.md), you must provide a sourcecommand followed by an optional series of processing commands, separated by pipe characters (|). For example:
56
+
* If you use [ES|QL](../../../explore-analyze/query-filter/languages/esql.md), you must provide a sourcecommand followed by an optional series of processing commands, separated by pipe characters (|).
54
57
55
-
```sh
56
-
FROM kibana_sample_data_logs
57
-
| STATS total_bytes = SUM(bytes) BY host
58
-
| WHERE total_bytes > 200000
59
-
| SORT total_bytes DESC
60
-
| LIMIT 10
61
-
```
58
+
For example:
59
+
60
+
```sh
61
+
FROM kibana_sample_data_logs
62
+
| STATS total_bytes = SUM(bytes) BY host
63
+
| WHERE total_bytes > 200000
64
+
| SORT total_bytes DESC
65
+
| LIMIT 10
66
+
```
67
+
68
+
2. Specify details for grouping alerts based on your query language.
69
+
70
+
* If you use query DSL, KQL, or Lucene, set the group and theshold.
71
+
72
+
When
73
+
: 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.
74
+
75
+
Over or Grouped Over
76
+
: Specify whether the aggregation is applied over all documents or split into groups using up to four grouping fields. If you choose to use grouping, it’s a [terms](elasticsearch://reference/aggregations/search-aggregations-bucket-terms-aggregation.md) or [multi terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-multi-terms-aggregation.md); an alert will be created for each unique set of values 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.
62
77
63
-
2. If you use query DSL, KQL, or Lucene, set the group and theshold.
78
+
Threshold
79
+
: 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.
64
80
65
-
When
66
-
: 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.
81
+
* {applies_to}`stack: ga 9.2` If you use {{esql}}, specify a time field and how to group alerts.
67
82
68
-
Over or Grouped Over
69
-
:Specify whether the aggregation is applied over all documents or split into groups using up to four grouping fields. If you choose to use grouping, it’s a [terms](elasticsearch://reference/aggregations/search-aggregations-bucket-terms-aggregation.md) or [multi terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-multi-terms-aggregation.md); an alert will be created foreach unique set of values 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.
83
+
Time field
84
+
: Choose the time field to use when filtering query results by the time window that you later specify for the rule. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field.
70
85
71
-
Threshold
72
-
: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.
86
+
Alert group
87
+
:Select **Create an alert if matches are found** to create a single alert for multiple events matching the {{esql}} query. Select **Create an alert for each row** to create a separate alert for each event that matches the {{esql}} query. Whenever possible, each alert is given a unique ID.
73
88
74
89
3. Set the time window, which defines how far back to search for documents.
75
90
4. If you use query DSL, KQL, or Lucene, set the number of documents to send to the configured actions when the threshold condition is met.
0 commit comments