Add Watcher API examples (#3489) (#3495)

Co-authored-by: István Zoltán Szabó <[email protected]>
(cherry picked from commit 2da56ac)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -789,12 +789,6 @@
       ],
       "response": []
     },
-    "watcher.stop": {
-      "request": [
-        "Request: missing json spec query parameter 'master_timeout'"
-      ],
-      "response": []
-    },
     "watcher.update_settings": {
       "request": [
         "Missing request & response"

output/schema/schema.json

@@ -493,6 +493,7 @@ run-as-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch
 runtime-search-request,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html
 script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html
 scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results
+search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after
 search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html
 search-aggregations-bucket-adjacency-matrix-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-adjacency-matrix-aggregation.html
 search-aggregations-bucket-autodatehistogram-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-autodatehistogram-aggregation.html

output/schema/validation-errors.json

@@ -3,4 +3,4 @@ description: A successful response for creating an auto-follow pattern.
 # type: response
 # response_code: 200
 value:
-  acknowledged": true
+  acknowledged: true

output/typescript/types.ts

@@ -92,6 +92,12 @@ export class ExecutionResultInput {
 }
 
 export class ExecutionThreadPool {
+  /**
+   * The largest size of the execution thread pool, which indicates the largest number of concurrent running watches.
+   */
   max_size: long
+  /**
+   * The number of watches that were triggered and are currently queued.
+   */
   queue_size: long
 }

specification/_doc_ids/table.csv

@@ -28,13 +28,24 @@ import { Name, Names } from '@_types/common'
  *
  * IMPORTANT: If the specified watch is currently being executed, this API will return an error
  * The reason for this behavior is to prevent overwriting the watch status from a watch execution.
+ *
+ * Acknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.
+ * This happens when the condition of the watch is not met (the condition evaluates to false).
  * @rest_spec_name watcher.ack_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-ack-watch
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     watch_id: Name
+    /**
+     * A comma-separated list of the action identifiers to acknowledge.
+     * If you omit this parameter, all of the actions of the watch are acknowledged.
+     */
     action_id?: Names
   }
 }

specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml

@@ -0,0 +1,33 @@
+# summary:
+description: A successful response from `POST _watcher/watch/my_watch/_ack`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "status": {
+      "state": {
+        "active": true,
+        "timestamp": "2015-05-26T18:04:27.723Z"
+      },
+      "last_checked": "2015-05-26T18:04:27.753Z",
+      "last_met_condition": "2015-05-26T18:04:27.763Z",
+      "actions": {
+        "test_index": {
+          "ack" : {
+            "timestamp": "2015-05-26T18:04:27.713Z",
+            "state": "acked"
+          },
+          "last_execution" : {
+            "timestamp": "2015-05-25T18:04:27.733Z",
+            "successful": true
+          },
+          "last_successful_execution" : {
+            "timestamp": "2015-05-25T18:04:27.773Z",
+            "successful": true
+          }
+        }
+      },
+      "execution_state": "executed",
+      "version": 2
+    }
+  }

specification/watcher/_types/Execution.ts

@@ -26,10 +26,14 @@ import { Name } from '@_types/common'
  * @rest_spec_name watcher.activate_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-activate-watch
  * @ext_doc_id watcher-works
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     watch_id: Name
   }
 }

specification/watcher/ack_watch/WatcherAckWatchRequest.ts

@@ -26,10 +26,14 @@ import { Name } from '@_types/common'
  * @rest_spec_name watcher.deactivate_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-deactivate-watch
  * @ext_doc_id watcher-works
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     watch_id: Name
   }
 }

specification/watcher/ack_watch/examples/response/WatcherAckWatchResponseExample1.yaml

@@ -32,9 +32,13 @@ import { Name } from '@_types/common'
  * @rest_spec_name watcher.delete_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-delete-watch
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     id: Name
   }
 }

specification/watcher/activate_watch/WatcherActivateWatchRequest.ts

@@ -0,0 +1,10 @@
+# summary:
+description: A successful response from `DELETE _watcher/watch/my_watch`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "found": true,
+    "_id": "my_watch",
+    "_version": 2
+  }

specification/watcher/deactivate_watch/DeactivateWatchRequest.ts

@@ -35,14 +35,20 @@ import { Id } from '@_types/common'
  *
  * You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.
  * This serves as great tool for testing and debugging your watches prior to adding them to Watcher.
+ *
+ * When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.
+ * If your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.
+ *
+ * When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.
  * @rest_spec_name watcher.execute_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-execute-watch
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Identifier for the watch.
+     * The watch identifier.
      */
     id?: Id
   }
@@ -68,17 +74,20 @@ export interface Request extends RequestBase {
      */
     ignore_condition?: boolean
     /**
-     * When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter.
+     * When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time.
+     * In addition, the status of the watch is updated, possibly throttling subsequent runs.
+     * This can also be specified as an HTTP parameter.
      * @server_default false
      */
     record_execution?: boolean
     simulated_actions?: SimulatedActions
     /**
-     * This structure is parsed as the data of the trigger event that will be used during the watch execution
+     * This structure is parsed as the data of the trigger event that will be used during the watch execution.
      */
     trigger_data?: ScheduleTriggerEvent
     /**
-     * When present, this watch is used instead of the one specified in the request. This watch is not persisted to the index and record_execution cannot be set.
+     * When present, this watch is used instead of the one specified in the request.
+     * This watch is not persisted to the index and `record_execution` cannot be set.
      * @server_default null
      */
     watch?: Watch

specification/watcher/delete_watch/DeleteWatchRequest.ts

@@ -21,5 +21,14 @@ import { Id } from '@_types/common'
 import { WatchRecord } from './types'
 
 export class Response {
-  body: { _id: Id; watch_record: WatchRecord }
+  body: {
+    /**
+     * The watch record identifier as it would be stored in the `.watcher-history` index.
+     */
+    _id: Id
+    /**
+     * The watch record document as it would be stored in the `.watcher-history` index.
+     */
+    watch_record: WatchRecord
+  }
 }

specification/watcher/delete_watch/examples/response/DeleteWatchResponseExample1.yaml

@@ -0,0 +1,24 @@
+summary: Run a watch
+# method_request: POST _watcher/watch/my_watch/_execute
+description: >
+  Run `POST _watcher/watch/my_watch/_execute` to run a watch.
+  The input defined in the watch is ignored and the `alternative_input` is used as the payload.
+  The condition as defined by the watch is ignored and is assumed to evaluate to true.
+  The `force_simulate` action forces the simulation of `my-action`.
+  Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally.
+# type: request
+value: |-
+  {
+    "trigger_data" : { 
+      "triggered_time" : "now",
+      "scheduled_time" : "now"
+    },
+    "alternative_input" : { 
+      "foo" : "bar"
+    },
+    "ignore_condition" : true, 
+    "action_modes" : {
+      "my-action" : "force_simulate" 
+    },
+    "record_execution" : true 
+  }

specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts

@@ -0,0 +1,12 @@
+summary: Run a watch with multiple action modes
+# method_request: POST _watcher/watch/my_watch/_execute
+description: >
+  Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action.
+# type: request
+value: |-
+  {
+    "action_modes" : {
+      "action1" : "force_simulate",
+      "action2" : "skip"
+    }
+  }

specification/watcher/execute_watch/WatcherExecuteWatchResponse.ts

@@ -0,0 +1,35 @@
+summary: Run a watch inline
+# method_request: POST _watcher/watch/_execute
+description: >
+  Run `POST _watcher/watch/_execute` to run a watch inline.
+  All other settings for this API still apply when inlining a watch.
+  In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored.
+# type: request
+value: |-
+  {
+    "watch" : {
+      "trigger" : { "schedule" : { "interval" : "10s" } },
+      "input" : {
+        "search" : {
+          "request" : {
+            "indices" : [ "logs" ],
+            "body" : {
+              "query" : {
+                "match" : { "message": "error" }
+              }
+            }
+          }
+        }
+      },
+      "condition" : {
+        "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
+      },
+      "actions" : {
+        "log_error" : {
+          "logging" : {
+            "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
+          }
+        }
+      }
+    }
+  }