[OAS] Add more Elasticsearch query rule examples (#164386)

elastic · Aug 28, 2023 · eaf9269 · eaf9269
1 parent f8ad13a
commit eaf9269
Show file tree

Hide file tree

Showing 8 changed files with 404 additions and 41 deletions.
diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.json b/x-pack/plugins/alerting/docs/openapi/bundled.json
@@ -60,6 +60,9 @@
                 "createEsQueryRuleRequest": {
                   "$ref": "#/components/examples/create_es_query_rule_request"
                 },
+                "createEsQueryKqlRuleRequest": {
+                  "$ref": "#/components/examples/create_es_query_kql_rule_request"
+                },
                 "createIndexThresholdRuleRequest": {
                   "$ref": "#/components/examples/create_index_threshold_rule_request"
                 }
@@ -79,6 +82,9 @@
                   "createEsQueryRuleResponse": {
                     "$ref": "#/components/examples/create_es_query_rule_response"
                   },
+                  "createEsQueryKqlRuleResponse": {
+                    "$ref": "#/components/examples/create_es_query_kql_rule_response"
+                  },
                   "createIndexThresholdRuleResponse": {
                     "$ref": "#/components/examples/create_index_threshold_rule_response"
                   }
@@ -263,6 +269,9 @@
                 "createEsQueryRuleIdRequest": {
                   "$ref": "#/components/examples/create_es_query_rule_request"
                 },
+                "createEsQueryKqlRuleIdRequest": {
+                  "$ref": "#/components/examples/create_es_query_kql_rule_request"
+                },
                 "createIndexThreholdRuleIdRequest": {
                   "$ref": "#/components/examples/create_index_threshold_rule_request"
                 }
@@ -282,6 +291,9 @@
                   "createEsQueryRuleIdResponse": {
                     "$ref": "#/components/examples/create_es_query_rule_response"
                   },
+                  "createEsQueryKqlRuleIdResponse": {
+                    "$ref": "#/components/examples/create_es_query_kql_rule_response"
+                  },
                   "createIndexThresholdRuleIdResponse": {
                     "$ref": "#/components/examples/create_index_threshold_rule_response"
                   }
@@ -6790,10 +6802,62 @@
     },
     "examples": {
       "create_es_query_rule_request": {
-        "summary": "Create an Elasticsearch query rule.",
+        "summary": "Create an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL) to define its query and a server log connector to send notifications.",
         "value": {
+          "actions": [
+            {
+              "group": "query matched",
+              "params": {
+                "level": "info",
+                "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
+              },
+              "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
+              "frequency": {
+                "throttle": "1d",
+                "summary": true,
+                "notify_when": "onThrottleInterval"
+              }
+            },
+            {
+              "group": "recovered",
+              "params": {
+                "level": "info",
+                "message": "Recovered"
+              },
+              "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
+              "frequency": {
+                "summary": false,
+                "notify_when": "onActionGroupChange"
+              }
+            }
+          ],
           "consumer": "alerts",
           "name": "my Elasticsearch query rule",
+          "params": {
+            "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
+            "index": [
+              "kibana_sample_data_logs"
+            ],
+            "size": 100,
+            "threshold": [
+              100
+            ],
+            "thresholdComparator": ">",
+            "timeField": "@timestamp",
+            "timeWindowSize": 1,
+            "timeWindowUnit": "d"
+          },
+          "rule_type_id": ".es-query",
+          "schedule": {
+            "interval": "1d"
+          }
+        }
+      },
+      "create_es_query_kql_rule_request": {
+        "summary": "Create an Elasticsearch query rule that uses Kibana query language (KQL).",
+        "value": {
+          "consumer": "alerts",
+          "name": "my Elasticsearch query KQL rule",
           "params": {
             "aggType": "count",
             "excludeHitsFromPreviousRun": true,
@@ -6866,11 +6930,92 @@
         }
       },
       "create_es_query_rule_response": {
+        "summary": "The create rule API returns a JSON object that contains details about the rule.",
+        "value": {
+          "id": "58148c70-407f-11ee-850e-c71febc4ca7f",
+          "enabled": true,
+          "name": "my Elasticsearch query rule",
+          "tags": [],
+          "rule_type_id": ".es-query",
+          "consumer": "alerts",
+          "schedule": {
+            "interval": "1d"
+          },
+          "actions": [
+            {
+              "group": "query matched",
+              "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
+              "params": {
+                "level": "info",
+                "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
+              },
+              "connector_type_id": ".server-log",
+              "frequency": {
+                "summary": true,
+                "notify_when": "onThrottleInterval",
+                "throttle": "1d"
+              },
+              "uuid": "53f3c2a3-e5d0-4cfa-af3b-6f0881385e78"
+            },
+            {
+              "group": "recovered",
+              "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
+              "params": {
+                "level": "info",
+                "message": "Recovered"
+              },
+              "connector_type_id": ".server-log",
+              "frequency": {
+                "summary": false,
+                "notify_when": "onActionGroupChange",
+                "throttle": null
+              },
+              "uuid": "2324e45b-c0df-45c7-9d70-4993e30be758"
+            }
+          ],
+          "params": {
+            "thresholdComparator": ">",
+            "timeWindowSize": 1,
+            "timeWindowUnit": "d",
+            "threshold": [
+              100
+            ],
+            "size": 100,
+            "timeField": "@timestamp",
+            "index": [
+              "kibana_sample_data_logs"
+            ],
+            "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
+            "excludeHitsFromPreviousRun": true,
+            "aggType": "count",
+            "groupBy": "all",
+            "searchType": "esQuery"
+          },
+          "scheduled_task_id": "58148c70-407f-11ee-850e-c71febc4ca7f",
+          "created_by": "elastic",
+          "updated_by": "elastic",
+          "created_at": "2023-08-22T00:03:38.263Z",
+          "updated_at": "2023-08-22T00:03:38.263Z",
+          "api_key_owner": "elastic",
+          "api_key_created_by_user": false,
+          "throttle": null,
+          "mute_all": false,
+          "notify_when": null,
+          "muted_alert_ids": [],
+          "execution_status": {
+            "status": "pending",
+            "last_execution_date": "2023-08-22T00:03:38.263Z"
+          },
+          "revision": 0,
+          "running": false
+        }
+      },
+      "create_es_query_kql_rule_response": {
         "summary": "The create rule API returns a JSON object that contains details about the rule.",
         "value": {
           "id": "7bd506d0-2284-11ee-8fad-6101956ced88",
           "enabled": true,
-          "name": "my Elasticsearch query rule\"",
+          "name": "my Elasticsearch query KQL rule\"",
           "tags": [],
           "rule_type_id": ".es-query",
           "consumer": "alerts",

diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.yaml b/x-pack/plugins/alerting/docs/openapi/bundled.yaml
@@ -38,6 +38,8 @@ paths:
             examples:
               createEsQueryRuleRequest:
                 $ref: '#/components/examples/create_es_query_rule_request'
+              createEsQueryKqlRuleRequest:
+                $ref: '#/components/examples/create_es_query_kql_rule_request'
               createIndexThresholdRuleRequest:
                 $ref: '#/components/examples/create_index_threshold_rule_request'
       responses:
@@ -50,6 +52,8 @@ paths:
               examples:
                 createEsQueryRuleResponse:
                   $ref: '#/components/examples/create_es_query_rule_response'
+                createEsQueryKqlRuleResponse:
+                  $ref: '#/components/examples/create_es_query_kql_rule_response'
                 createIndexThresholdRuleResponse:
                   $ref: '#/components/examples/create_index_threshold_rule_response'
         '401':
@@ -158,6 +162,8 @@ paths:
             examples:
               createEsQueryRuleIdRequest:
                 $ref: '#/components/examples/create_es_query_rule_request'
+              createEsQueryKqlRuleIdRequest:
+                $ref: '#/components/examples/create_es_query_kql_rule_request'
               createIndexThreholdRuleIdRequest:
                 $ref: '#/components/examples/create_index_threshold_rule_request'
       responses:
@@ -170,6 +176,8 @@ paths:
               examples:
                 createEsQueryRuleIdResponse:
                   $ref: '#/components/examples/create_es_query_rule_response'
+                createEsQueryKqlRuleIdResponse:
+                  $ref: '#/components/examples/create_es_query_kql_rule_response'
                 createIndexThresholdRuleIdResponse:
                   $ref: '#/components/examples/create_index_threshold_rule_response'
         '401':
@@ -4633,10 +4641,47 @@ components:
           example: elastic
   examples:
     create_es_query_rule_request:
-      summary: Create an Elasticsearch query rule.
+      summary: Create an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL) to define its query and a server log connector to send notifications.
       value:
+        actions:
+          - group: query matched
+            params:
+              level: info
+              message: The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts.
+            id: fdbece50-406c-11ee-850e-c71febc4ca7f
+            frequency:
+              throttle: 1d
+              summary: true
+              notify_when: onThrottleInterval
+          - group: recovered
+            params:
+              level: info
+              message: Recovered
+            id: fdbece50-406c-11ee-850e-c71febc4ca7f
+            frequency:
+              summary: false
+              notify_when: onActionGroupChange
         consumer: alerts
         name: my Elasticsearch query rule
+        params:
+          esQuery: '"""{"query":{"match_all" : {}}}"""'
+          index:
+            - kibana_sample_data_logs
+          size: 100
+          threshold:
+            - 100
+          thresholdComparator: '>'
+          timeField: '@timestamp'
+          timeWindowSize: 1
+          timeWindowUnit: d
+        rule_type_id: .es-query
+        schedule:
+          interval: 1d
+    create_es_query_kql_rule_request:
+      summary: Create an Elasticsearch query rule that uses Kibana query language (KQL).
+      value:
+        consumer: alerts
+        name: my Elasticsearch query KQL rule
         params:
           aggType: count
           excludeHitsFromPreviousRun: true
@@ -4695,11 +4740,76 @@ components:
         tags:
           - cpu
     create_es_query_rule_response:
+      summary: The create rule API returns a JSON object that contains details about the rule.
+      value:
+        id: 58148c70-407f-11ee-850e-c71febc4ca7f
+        enabled: true
+        name: my Elasticsearch query rule
+        tags: []
+        rule_type_id: .es-query
+        consumer: alerts
+        schedule:
+          interval: 1d
+        actions:
+          - group: query matched
+            id: fdbece50-406c-11ee-850e-c71febc4ca7f
+            params:
+              level: info
+              message: The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts.
+            connector_type_id: .server-log
+            frequency:
+              summary: true
+              notify_when: onThrottleInterval
+              throttle: 1d
+            uuid: 53f3c2a3-e5d0-4cfa-af3b-6f0881385e78
+          - group: recovered
+            id: fdbece50-406c-11ee-850e-c71febc4ca7f
+            params:
+              level: info
+              message: Recovered
+            connector_type_id: .server-log
+            frequency:
+              summary: false
+              notify_when: onActionGroupChange
+              throttle: null
+            uuid: 2324e45b-c0df-45c7-9d70-4993e30be758
+        params:
+          thresholdComparator: '>'
+          timeWindowSize: 1
+          timeWindowUnit: d
+          threshold:
+            - 100
+          size: 100
+          timeField: '@timestamp'
+          index:
+            - kibana_sample_data_logs
+          esQuery: '"""{"query":{"match_all" : {}}}"""'
+          excludeHitsFromPreviousRun: true
+          aggType: count
+          groupBy: all
+          searchType: esQuery
+        scheduled_task_id: 58148c70-407f-11ee-850e-c71febc4ca7f
+        created_by: elastic
+        updated_by: elastic
+        created_at: '2023-08-22T00:03:38.263Z'
+        updated_at: '2023-08-22T00:03:38.263Z'
+        api_key_owner: elastic
+        api_key_created_by_user: false
+        throttle: null
+        mute_all: false
+        notify_when: null
+        muted_alert_ids: []
+        execution_status:
+          status: pending
+          last_execution_date: '2023-08-22T00:03:38.263Z'
+        revision: 0
+        running: false
+    create_es_query_kql_rule_response:
       summary: The create rule API returns a JSON object that contains details about the rule.
       value:
         id: 7bd506d0-2284-11ee-8fad-6101956ced88
         enabled: true
-        name: my Elasticsearch query rule"
+        name: my Elasticsearch query KQL rule"
         tags: []
         rule_type_id: .es-query
         consumer: alerts

diff --git a/...k/plugins/alerting/docs/openapi/components/examples/create_es_query_kql_rule_request.yaml b/...k/plugins/alerting/docs/openapi/components/examples/create_es_query_kql_rule_request.yaml
@@ -0,0 +1,23 @@
+summary: Create an Elasticsearch query rule that uses Kibana query language (KQL).
+value:
+  consumer: alerts
+  name: my Elasticsearch query KQL rule
+  params:
+    aggType: count
+    excludeHitsFromPreviousRun: true
+    groupBy: all
+    searchConfiguration:
+      query:
+        query: '""geo.src : "US" ""'
+        language: kuery
+      index: 90943e30-9a47-11e8-b64d-95841ca0b247
+    searchType: searchSource
+    size: 100
+    threshold:
+      - 1000
+    thresholdComparator: ">"
+    timeWindowSize: 5
+    timeWindowUnit: m
+  rule_type_id: .es-query
+  schedule:
+    interval: 1m