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

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",

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

x-pack/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

x-pack/plugins/alerting/docs/openapi/components/examples/create_es_query_kql_rule_response.yaml

@@ -0,0 +1,43 @@
+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 KQL rule"
+  tags: []
+  rule_type_id: .es-query
+  consumer: alerts
+  schedule: 
+    interval: 1m
+  actions: []
+  params: 
+    searchConfiguration:
+      query:
+        query: '""geo.src : "US" ""'
+        language: kuery
+      index: 90943e30-9a47-11e8-b64d-95841ca0b247
+    searchType: searchSource
+    timeWindowSize: 5
+    timeWindowUnit: m
+    threshold:
+      - 1000
+    thresholdComparator: ">"
+    size: 100
+    aggType: count
+    groupBy: all
+    excludeHitsFromPreviousRun: true
+  created_by: elastic
+  updated_by: elastic
+  created_at: '2023-07-14T20:24:50.729Z'
+  updated_at: '2023-07-14T20:24:50.729Z'
+  api_key_owner: elastic
+  api_key_created_by_user: false
+  throttle: null
+  notify_when: null
+  mute_all: false
+  muted_alert_ids: []
+  scheduled_task_id: 7bd506d0-2284-11ee-8fad-6101956ced88
+  execution_status:
+    status: pending
+    last_execution_date: '2023-07-14T20:24:50.729Z'
+  revision: 0
+  running: false

x-pack/plugins/alerting/docs/openapi/components/examples/create_es_query_rule_request.yaml

@@ -1,23 +1,36 @@
-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:
-    aggType: count
-    excludeHitsFromPreviousRun: true
-    groupBy: all
-    searchConfiguration:
-      query:
-        query: '""geo.src : "US" ""'
-        language: kuery
-      index: 90943e30-9a47-11e8-b64d-95841ca0b247
-    searchType: searchSource
+  params:    
+    esQuery: '"""{"query":{"match_all" : {}}}"""'
+    index:
+      - kibana_sample_data_logs
     size: 100
     threshold:
-      - 1000
+      - 100
     thresholdComparator: ">"
-    timeWindowSize: 5
-    timeWindowUnit: m
+    timeField: "@timestamp"
+    timeWindowSize: 1
+    timeWindowUnit: d
   rule_type_id: .es-query
   schedule:
-    interval: 1m
+    interval: 1d

x-pack/plugins/alerting/docs/openapi/components/examples/create_es_query_rule_response.yaml

@@ -1,43 +1,64 @@
 summary: The create rule API returns a JSON object that contains details about the rule.
 value:
-  id: 7bd506d0-2284-11ee-8fad-6101956ced88
+  id: 58148c70-407f-11ee-850e-c71febc4ca7f
   enabled: true
-  name: my Elasticsearch query rule"
+  name: my Elasticsearch query rule
   tags: []
   rule_type_id: .es-query
   consumer: alerts
-  schedule: 
-    interval: 1m
-  actions: []
-  params: 
-    searchConfiguration:
-      query:
-        query: '""geo.src : "US" ""'
-        language: kuery
-      index: 90943e30-9a47-11e8-b64d-95841ca0b247
-    searchType: searchSource
-    timeWindowSize: 5
-    timeWindowUnit: m
-    threshold:
-      - 1000
+  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
-    excludeHitsFromPreviousRun: true
+    searchType: esQuery
+  scheduled_task_id: 58148c70-407f-11ee-850e-c71febc4ca7f
   created_by: elastic
   updated_by: elastic
-  created_at: '2023-07-14T20:24:50.729Z'
-  updated_at: '2023-07-14T20:24:50.729Z'
+  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
-  notify_when: null
   mute_all: false
+  notify_when: null
   muted_alert_ids: []
-  scheduled_task_id: 7bd506d0-2284-11ee-8fad-6101956ced88
   execution_status:
     status: pending
-    last_execution_date: '2023-07-14T20:24:50.729Z'
+    last_execution_date: '2023-08-22T00:03:38.263Z'
   revision: 0
   running: false

x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule.yaml

@@ -23,6 +23,8 @@ post:
         examples:
           createEsQueryRuleRequest:
             $ref: '../components/examples/create_es_query_rule_request.yaml'
+          createEsQueryKqlRuleRequest:
+            $ref: '../components/examples/create_es_query_kql_rule_request.yaml'
           createIndexThresholdRuleRequest:
             $ref: '../components/examples/create_index_threshold_rule_request.yaml'
   responses:
@@ -35,6 +37,8 @@ post:
           examples:
             createEsQueryRuleResponse:
               $ref: '../components/examples/create_es_query_rule_response.yaml'
+            createEsQueryKqlRuleResponse:
+              $ref: '../components/examples/create_es_query_kql_rule_response.yaml'
             createIndexThresholdRuleResponse:
               $ref: '../components/examples/create_index_threshold_rule_response.yaml'
     '401':

x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule@{ruleid}.yaml

@@ -104,6 +104,8 @@ post:
         examples:
           createEsQueryRuleIdRequest:
             $ref: '../components/examples/create_es_query_rule_request.yaml'
+          createEsQueryKqlRuleIdRequest:
+            $ref: '../components/examples/create_es_query_kql_rule_request.yaml'
           createIndexThreholdRuleIdRequest:
             $ref: '../components/examples/create_index_threshold_rule_request.yaml'
   responses:
@@ -116,6 +118,8 @@ post:
           examples:
             createEsQueryRuleIdResponse:
               $ref: '../components/examples/create_es_query_rule_response.yaml'
+            createEsQueryKqlRuleIdResponse:
+              $ref: '../components/examples/create_es_query_kql_rule_response.yaml'
             createIndexThresholdRuleIdResponse:
               $ref: '../components/examples/create_index_threshold_rule_response.yaml'
     '401':