Skip to content

Commit a038dc3

Browse files
[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]>
1 parent e5c63da commit a038dc3

File tree

4 files changed

+68
-42
lines changed

4 files changed

+68
-42
lines changed

explore-analyze/alerts-cases/alerts/rule-type-es-query.md

Lines changed: 32 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ When you create an {{es}} query rule, your choice of query type affects the info
2626

2727
1. Define your query
2828

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:
3030

3131
```sh
3232
{
@@ -36,34 +36,45 @@ When you create an {{es}} query rule, your choice of query type affects the info
3636
}
3737
```
3838

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"`.
4040

41-
If you use [ES|QL](../../query-filter/languages/esql.md), you must provide a source command 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 source command followed by an optional series of processing commands, separated by pipe characters (|).
4242

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+
:::
4646

47-
For example:
47+
For example:
4848

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.
5666

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.
5869

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.
6171

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 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.
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.
6474

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+
6778

6879
3. Set the time window, which defines how far back to search for documents.
6980
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.
-28.3 KB
Loading
-28.3 KB
Loading

solutions/observability/incident-management/create-an-elasticsearch-query-rule.md

Lines changed: 36 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
navigation_title: Elasticsearch query
33
mapped_pages:
44
- https://www.elastic.co/guide/en/serverless/current/observability-create-elasticsearch-query-rule.html
5+
applies_to:
6+
stack: ga
7+
serverless: ga
58
products:
69
- id: cloud-serverless
710
---
@@ -38,38 +41,50 @@ When you create an {{es}} query rule, your choice of query type affects the info
3841

3942
1. Define your query
4043

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:
4245

4346
```sh
4447
{
45-
"query":{
46-
"match_all" : {}
47-
}
48-
}
48+
"query":{
49+
"match_all" : {}
50+
}
51+
}
4952
```
5053

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"`.
5255

53-
If you use [ES|QL](/explore-analyze/query-filter/languages/esql.md), you must provide a source command 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 source command followed by an optional series of processing commands, separated by pipe characters (|).
5457

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.
6277

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.
6480

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.
6782

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 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.
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.
7085

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.
7388

7489
3. Set the time window, which defines how far back to search for documents.
7590
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

Comments
 (0)