[Alerting] Search alert (#88528)

* Adding es query alert type to server with commented out executor * Adding skeleton es query alert to client with JSON editor. Pulled out index popoover into component for reuse between index threshold and es query alert types * Implementing alert executor that performs query and matches condition against doc count * Added tests for server side alert type * Updated alert executor to de-duplicate matches and create instance for every document if threshold is not defined * Moving more index popover code out of index threshold and es query expression components * Ability to remove threshold condition from es query alert * Validation tests * Adding ability to test out query. Need to add error handling and it looks ugly * Fixing bug with creating alert with threshold and i18n * wip * Fixing tests * Simplifying executor logic to only handle threshold and store hits in action context * Adding functional test for es query alert * Types * Adding functional test for query testing * Fixing unit test * Adding link to ES docs. Cleaning up logger statements * Adding docs * Updating docs based on feedback * PR fixes * Using ES client typings * Fixing unit test * Fixing copy based on comments * Fixing copy based on comments * Fixing bug in index select popover * Fixing unit tests * Making track_total_hits configurable * Fixing functional test * PR fixes * Added unit test * Removing unused import Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
elastic · Jan 29, 2021 · 0491351 · 0491351
1 parent 9733d2f
commit 0491351
Show file tree

Hide file tree

Showing 45 changed files with 3,072 additions and 294 deletions.
diff --git a/docs/user/alerting/alert-types.asciidoc b/docs/user/alerting/alert-types.asciidoc
@@ -8,7 +8,7 @@ This section covers stack alerts. For domain-specific alert types, refer to the
 Users will need `all` access to the *Stack Alerts* feature to be able to create and edit any of the alerts listed below.
 See <<kibana-feature-privileges, feature privileges>> for more information on configuring roles that provide access to this feature. 
 
-Currently {kib} provides one stack alert: the <<alert-type-index-threshold>> type.
+Currently {kib} provides two stack alerts: <<alert-type-index-threshold>> and <<alert-type-es-query>>.
 
 [float]
 [[alert-type-index-threshold]]
@@ -112,6 +112,47 @@ You can interactively change the time window and observe the effect it has on th
 [role="screenshot"]
 image::images/alert-types-index-threshold-example-comparison.png[Comparing two time windows]
 
+[float]
+[[alert-type-es-query]]
+=== ES query
+
+The ES query alert type is designed to run a user-configured {es} query over indices, compare the number of matches to a configured threshold, and schedule
+actions to run when the threshold condition is met.
+
+[float]
+==== Creating the alert
+
+An ES query alert can be created from the *Create* button in the <<alert-management, alert management UI>>. Fill in the <<defining-alerts-general-details, general alert details>>, then select *ES query*.
+
+[role="screenshot"]
+image::images/alert-types-es-query-select.png[Choosing an ES query alert type]
+
+[float]
+==== Defining the conditions
 
+The ES query alert has 4 clauses that define the condition to detect.
 
+[role="screenshot"]
+image::images/alert-types-es-query-conditions.png[Four 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*.
+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 alert details>>, to avoid gaps in detection. 
+
+[float]
+==== Testing your query
+
+Use the *Test query* feature to verify that your query DSL is valid.
 
+When your query is valid:: Valid queries will be executed against the configured *index* using the configured *time window*. The number of documents that
+match the query will be displayed.
+
+[role="screenshot"]
+image::images/alert-types-es-query-valid.png[Test ES query returns number of matches when valid]
+
+When your query is invalid:: An error message is shown if the query is invalid.
+
+[role="screenshot"]
+image::images/alert-types-es-query-invalid.png[Test ES query shows error when invalid]
diff --git a/docs/user/alerting/images/alert-types-es-query-conditions.png b/docs/user/alerting/images/alert-types-es-query-conditions.png
diff --git a/docs/user/alerting/images/alert-types-es-query-invalid.png b/docs/user/alerting/images/alert-types-es-query-invalid.png
diff --git a/docs/user/alerting/images/alert-types-es-query-select.png b/docs/user/alerting/images/alert-types-es-query-select.png
diff --git a/docs/user/alerting/images/alert-types-es-query-valid.png b/docs/user/alerting/images/alert-types-es-query-valid.png
diff --git a/x-pack/plugins/alerts/common/index.ts b/x-pack/plugins/alerts/common/index.ts
@@ -15,6 +15,7 @@ export * from './alert_instance_summary';
 export * from './builtin_action_groups';
 export * from './disabled_action_groups';
 export * from './alert_notify_when_type';
+export * from './parse_duration';
 
 export interface AlertingFrameworkHealth {
   isSufficientlySecure: boolean;