From dd3b3f929dd022b2b1a745fa6b6f4ceedf970353 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 2 Jul 2025 17:09:42 -0400 Subject: [PATCH 1/4] First draft --- .../alerts-cases/alerts/rule-type-es-query.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md index edd1f9164b..d9cf1c02f5 100644 --- a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md +++ b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md @@ -65,12 +65,21 @@ When you create an {{es}} query rule, your choice of query type affects the info 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. -3. Set the time window, which defines how far back to search for documents. -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. -5. If you use query DSL, KQL, or Lucene, choose whether to avoid alert duplication by excluding matches from the previous run. This option is not available when you use a grouping field. -6. Set the check interval, which defines how often to evaluate the rule conditions. Generally this value should be set to a value that is smaller than the time window, to avoid gaps in detection. -7. In the advanced options, you can change the number of consecutive runs that must meet the rule conditions before an alert occurs. The default value is `1`. -8. Select a scope value, which affects the [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) that are required to access the rule. For example when it’s set to `Stack Rules`, you must have the appropriate **Management > {{stack-rules-feature}}** feature privileges to view or edit the rule. +3. If you use {{esql}}, specify a time field and how to group alerts. + + Time field + : Specify the time field to use when filtering query results by the time window that you specify. You can choose `@timestamp`, `timestamp`, or `utc_time`. + + Alert group + : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. + + +4. Set the time window, which defines how far back to search for documents. +5. 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. +6. If you use query DSL, KQL, or Lucene, choose whether to avoid alert duplication by excluding matches from the previous run. This option is not available when you use a grouping field. +7. Set the check interval, which defines how often to evaluate the rule conditions. Generally this value should be set to a value that is smaller than the time window, to avoid gaps in detection. +8. In the advanced options, you can change the number of consecutive runs that must meet the rule conditions before an alert occurs. The default value is `1`. +9. Select a scope value, which affects the [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) that are required to access the rule. For example when it’s set to `Stack Rules`, you must have the appropriate **Management > {{stack-rules-feature}}** feature privileges to view or edit the rule. ## Test your query [_test_your_query] From 7dad94d13d6a92adadcd9ce37db9c4437e89afce Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 2 Jul 2025 17:11:52 -0400 Subject: [PATCH 2/4] obs docs --- .../create-an-elasticsearch-query-rule.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md index c96d836275..117013bf5a 100644 --- a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md +++ b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md @@ -71,10 +71,18 @@ When you create an {{es}} query rule, your choice of query type affects the info 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. -3. Set the time window, which defines how far back to search for documents. -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. -5. If you use query DSL, KQL, or Lucene, choose whether to avoid alert duplication by excluding matches from the previous run. This option is not available when you use a grouping field. -6. Set the check interval, which defines how often to evaluate the rule conditions. Generally this value should be set to a value that is smaller than the time window, to avoid gaps in detection. +3. If you use {{esql}}, specify a time field and how to group alerts. + + Time field + : Specify the time field to use when filtering query results by the time window that you specify. You can choose `@timestamp`, `timestamp`, or `utc_time`. + + Alert group + : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. + +4. Set the time window, which defines how far back to search for documents. +5. 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. +6. If you use query DSL, KQL, or Lucene, choose whether to avoid alert duplication by excluding matches from the previous run. This option is not available when you use a grouping field. +7. Set the check interval, which defines how often to evaluate the rule conditions. Generally this value should be set to a value that is smaller than the time window, to avoid gaps in detection. ## Test your query [observability-create-elasticsearch-query-rule-test-your-query] From 633f99becca2c0fc6afbbb882cec749a461fcc9d Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 2 Jul 2025 18:20:00 -0400 Subject: [PATCH 3/4] Refined time field description --- explore-analyze/alerts-cases/alerts/rule-type-es-query.md | 2 +- .../incident-management/create-an-elasticsearch-query-rule.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md index d9cf1c02f5..e87e50448d 100644 --- a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md +++ b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md @@ -68,7 +68,7 @@ When you create an {{es}} query rule, your choice of query type affects the info 3. If you use {{esql}}, specify a time field and how to group alerts. Time field - : Specify the time field to use when filtering query results by the time window that you specify. You can choose `@timestamp`, `timestamp`, or `utc_time`. + : Specify the time field to use when filtering query results by the time window that you specify. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field. Alert group : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. diff --git a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md index 117013bf5a..c5d03373bd 100644 --- a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md +++ b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md @@ -74,7 +74,7 @@ When you create an {{es}} query rule, your choice of query type affects the info 3. If you use {{esql}}, specify a time field and how to group alerts. Time field - : Specify the time field to use when filtering query results by the time window that you specify. You can choose `@timestamp`, `timestamp`, or `utc_time`. + : Choose the time field to use when filtering query results by the time window that you specify for the rule. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field. Alert group : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. From 3d569f1f39a9aa1639c7f39c1f574fd7f7b0a9c9 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 2 Jul 2025 18:34:35 -0400 Subject: [PATCH 4/4] revisions --- explore-analyze/alerts-cases/alerts/rule-type-es-query.md | 2 +- .../incident-management/create-an-elasticsearch-query-rule.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md index e87e50448d..49e43acd34 100644 --- a/explore-analyze/alerts-cases/alerts/rule-type-es-query.md +++ b/explore-analyze/alerts-cases/alerts/rule-type-es-query.md @@ -71,7 +71,7 @@ When you create an {{es}} query rule, your choice of query type affects the info : Specify the time field to use when filtering query results by the time window that you specify. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field. Alert group - : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. + : 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 will have a unique ID. 4. Set the time window, which defines how far back to search for documents. diff --git a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md index c5d03373bd..2c5d22d18b 100644 --- a/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md +++ b/solutions/observability/incident-management/create-an-elasticsearch-query-rule.md @@ -77,7 +77,7 @@ When you create an {{es}} query rule, your choice of query type affects the info : Choose the time field to use when filtering query results by the time window that you specify for the rule. You can choose any time field that's availble on the index you're querying, for example, the `@timestamp` field. Alert group - : Select **Create an alert if matches are found** to create a single alert when the query matches multiple events. Select **Create an alert for each row** to create an alert for each query match. Whenever possible, each alert will have a unique ID. + : 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 will have a unique ID. 4. Set the time window, which defines how far back to search for documents. 5. 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.