diff --git a/docs/en/rest-api/watcher/ack-watch.asciidoc b/docs/en/rest-api/watcher/ack-watch.asciidoc index b06896a9b12..cd04b047f7b 100644 --- a/docs/en/rest-api/watcher/ack-watch.asciidoc +++ b/docs/en/rest-api/watcher/ack-watch.asciidoc @@ -2,9 +2,37 @@ [[watcher-api-ack-watch]] === Ack Watch API -{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you to manually throttle -execution of the watch's actions. An action's _acknowledgement state_ is stored -in the `status.actions..ack.state` structure. +{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you +to manually throttle execution of the watch's actions. An action's +_acknowledgement state_ is stored in the `status.actions..ack.state` +structure. + +[float] +==== Request + +`PUT _xpack/watcher/watch//_ack` + + +`PUT _xpack/watcher/watch//_ack/` + +[float] +==== Path Parameters + +`action_id`:: + (list) A comma-separated list of the action IDs to acknowledge. If you omit + this parameter, all of the actions of the watch are acknowledged. + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + + +[float] +==== Examples To demonstrate let's create a new watch: diff --git a/docs/en/rest-api/watcher/activate-watch.asciidoc b/docs/en/rest-api/watcher/activate-watch.asciidoc index 7ef799c5196..aec5a42d224 100644 --- a/docs/en/rest-api/watcher/activate-watch.asciidoc +++ b/docs/en/rest-api/watcher/activate-watch.asciidoc @@ -6,6 +6,26 @@ A watch can be either {xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. This API enables you to activate a currently inactive watch. +[float] +==== Request + +`PUT _xpack/watcher/watch//_activate` + +[float] +==== Path Parameters + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + The status of an inactive watch is returned with the watch definition when you call the <>: diff --git a/docs/en/rest-api/watcher/deactivate-watch.asciidoc b/docs/en/rest-api/watcher/deactivate-watch.asciidoc index a10cbc3e34d..6729098cf3d 100644 --- a/docs/en/rest-api/watcher/deactivate-watch.asciidoc +++ b/docs/en/rest-api/watcher/deactivate-watch.asciidoc @@ -6,6 +6,25 @@ A watch can be either {xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. This API enables you to deactivate a currently active watch. +[float] +==== Request + +`PUT _xpack/watcher/watch//_deactivate` + +[float] +==== Path Parameters + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Authorization +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + The status of an active watch is returned with the watch definition when you call the <>: diff --git a/docs/en/rest-api/watcher/delete-watch.asciidoc b/docs/en/rest-api/watcher/delete-watch.asciidoc index d88f416c970..bedc60897e7 100644 --- a/docs/en/rest-api/watcher/delete-watch.asciidoc +++ b/docs/en/rest-api/watcher/delete-watch.asciidoc @@ -2,18 +2,42 @@ [[watcher-api-delete-watch]] === Delete Watch API -The DELETE watch API removes a watch (identified by its `id`) from {watcher}. -Once removed, the document representing the watch in the `.watches` index is -gone and it will never be executed again. +The DELETE watch API removes a watch from {watcher}. + +[float] +==== Request + +`DELETE _xpack/watcher/watch/` + +[float] +==== Description + +When the watch is removed, the document representing the watch in the `.watches` +index is gone and it will never be run again. Please note that deleting a watch **does not** delete any watch execution records related to this watch from the watch history. IMPORTANT: Deleting a watch must be done via this API only. Do not delete the - watch directly from the `.watches` index using Elasticsearch's + watch directly from the `.watches` index using the Elasticsearch DELETE Document API. When {security} is enabled, make sure no `write` privileges are granted to anyone over the `.watches` index. +[float] +==== Path Parameters + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + The following example deletes a watch with the `my-watch` id: [source,js] @@ -34,4 +58,3 @@ Response: } -------------------------------------------------- // TESTRESPONSE - diff --git a/docs/en/rest-api/watcher/execute-watch.asciidoc b/docs/en/rest-api/watcher/execute-watch.asciidoc index f98b46d3c3c..09b40c43d68 100644 --- a/docs/en/rest-api/watcher/execute-watch.asciidoc +++ b/docs/en/rest-api/watcher/execute-watch.asciidoc @@ -6,20 +6,45 @@ The execute watch API forces the execution of a stored watch. It can be used to force execution of the watch outside of its triggering logic, or to simulate the watch execution for debugging purposes. -The following example executes the `my_watch` watch: +[float] +==== Request -[source,js] --------------------------------------------------- -POST _xpack/watcher/watch/my_watch/_execute --------------------------------------------------- -// CONSOLE -// TEST[setup:my_active_watch] +`POST _xpack/watcher/watch//_execute` + -For testing and debugging purposes, you also have fine-grained control on how the -watch is executed--execute the watch without executing all of its actions or -alternatively by simulating them. You can also force execution by ignoring the -watch condition and control whether a watch record would be written to the watch -history after execution. +`POST _xpack/watcher/watch/_execute` + +[float] +==== Description + +For testing and debugging purposes, you also have fine-grained control on how +the watch runs. You can execute the watch without executing all of its actions +or alternatively by simulating them. You can also force execution by ignoring +the watch condition and control whether a watch record would be written to the +watch history after execution. + +[float] +[[watcher-api-execute-inline-watch]] +===== Inline Watch Execution + +You can use the Execute API to execute 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}. + +[float] +==== Path Parameters + +`watch_id`:: + (string) Identifier for the watch. + +[float] +==== Query Parameters + +`debug`:: + (boolean) Defines whether the watch runs in debug mode. The default value is + `false`. + +[float] +==== Request Body This API supports the following fields: @@ -53,6 +78,58 @@ This API supports the following fields: not persisted to the index and record_execution cannot be set. |====== +[float] +[[watcher-api-execute-watch-action-mode]] +===== Action Execution Modes + +Action modes define how actions are handled during the watch execution. There +are five possible modes an action can be associated with: + +[options="header"] +|====== +| Name | Description + +| `simulate` | The action execution is simulated. Each action type + define its own simulation operation mode. For example, the + {xpack-ref}/actions-email.html[email] action creates + the email that would have been sent but does not actually + send it. In this mode, the action might be throttled if the + current state of the watch indicates it should be. + +| `force_simulate` | Similar to the the `simulate` mode, except the action is + not be throttled even if the current state of the watch + indicates it should be. + +| `execute` | Executes the action as it would have been executed if the + watch would have been triggered by its own trigger. The + execution might be throttled if the current state of the + watch indicates it should be. + +| `force_execute` | Similar to the `execute` mode, except the action is not + throttled even if the current state of the watch indicates + it should be. + +| `skip` | The action is skipped and is not executed or simulated. + Effectively forces the action to be throttled. +|====== + +[float] +==== Authorization +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + +The following example executes the `my_watch` watch: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + The following example shows a comprehensive example of executing the `my-watch` watch: [source,js] @@ -77,14 +154,14 @@ POST _xpack/watcher/watch/my_watch/_execute // TEST[setup:my_active_watch] <1> The triggered and schedule times are provided. <2> The input as defined by the watch is ignored and instead the provided input - will be used as the execution payload. -<3> The condition as defined by the watch will be ignored and will be assumed to + is used as the execution payload. +<3> The condition as defined by the watch is ignored and is assumed to evaluate to `true`. <4> Forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by {watcher} instead of being executed normally. -<5> The execution of the watch will create a watch record in the watch history, - and the throttling state of the watch will potentially be updated accordingly. +<5> The execution of the watch creates a watch record in the watch history, + and the throttling state of the watch is potentially updated accordingly. This is an example of the output: @@ -192,40 +269,6 @@ This is an example of the output: <2> The watch record document as it would be stored in the `.watcher-history` index. <3> The watch execution results. -[[watcher-api-execute-watch-action-mode]] -==== Action Execution Modes - -Action modes define how actions are handled during the watch execution. There -are five possible modes an action can be associated with: - -[options="header"] -|====== -| Name | Description - -| `simulate` | The action execution will be simulated. Each action type - define its own simulation operation mode. For example, the - {xpack-ref}/actions-email.html[email] action will create - the email that would have been sent but will not actually - send it. In this mode, the action may be throttled if the - current state of the watch indicates it should be. - -| `force_simulate` | Similar to the the `simulate` mode, except the action will - not be throttled even if the current state of the watch - indicates it should be. - -| `execute` | Executes the action as it would have been executed if the - watch would have been triggered by its own trigger. The - execution may be throttled if the current state of the - watch indicates it should be. - -| `force_execute` | Similar to the `execute` mode, except the action will not - be throttled even if the current state of the watch - indicates it should be. - -| `skip` | The action will be skipped and won't be executed nor - simulated. Effectively forcing the action to be throttled. -|====== - You can set a different execution mode for every action by associating the mode name with the action id: @@ -257,14 +300,6 @@ POST _xpack/watcher/watch/my_watch/_execute // CONSOLE // TEST[setup:my_active_watch] -[float] -[[watcher-api-execute-inline-watch]] -==== Inline Watch Execution - -You can use the Execute API to execute 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}. - The following example shows how to execute a watch inline: [source,js] diff --git a/docs/en/rest-api/watcher/get-watch.asciidoc b/docs/en/rest-api/watcher/get-watch.asciidoc index 08bb5e872c7..9af20107bdd 100644 --- a/docs/en/rest-api/watcher/get-watch.asciidoc +++ b/docs/en/rest-api/watcher/get-watch.asciidoc @@ -2,7 +2,28 @@ [[watcher-api-get-watch]] === Get Watch API -This API retrieves a watch by its id. +This API retrieves a watch by its ID. + +[float] +==== Request + +`GET _xpack/watcher/watch/` + +[float] +==== Path Parameters + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Authorization + +You must have `manage_watcher` or `monitor_watcher` cluster privileges to use +this API. For more information, see +{xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples The following example gets a watch with `my-watch` id: diff --git a/docs/en/rest-api/watcher/put-watch.asciidoc b/docs/en/rest-api/watcher/put-watch.asciidoc index 468c01ac337..fcf61810dc7 100644 --- a/docs/en/rest-api/watcher/put-watch.asciidoc +++ b/docs/en/rest-api/watcher/put-watch.asciidoc @@ -3,16 +3,80 @@ === Put Watch API The PUT watch API either registers a new watch in {watcher} or update an -existing one. Once registered, a new document will be added to the `.watches` -index, representing the watch, and its trigger will immediately be registered -with the relevant trigger engine (typically the scheduler, for the `schedule` -trigger). +existing one. + +[float] +==== Request + +`PUT _xpack/watcher/watch/` + +[float] +==== Description + +When a watch is registered, a new document that represents the watch is added to +the `.watches` index and its trigger is immediately registered with the relevant +trigger engine. Typically for the `schedule` trigger, the scheduler is the +trigger engine. IMPORTANT: Putting a watch must be done via this API only. Do not put a watch - directly to the `.watches` index using Elasticsearch's Index API. + directly to the `.watches` index using the Elasticsearch Index API. If {security} is enabled, make sure no `write` privileges are granted to anyone over the `.watches` index. +When adding a watch you can also define its initial +{xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that +by setting the `active` parameter. + +[float] +==== Path Parameters + +`watch_id` (required):: + (string) Identifier for the watch. + +[float] +==== Query Parameters + +`active`:: + (boolean) Defines whether the watch is active or inactive by default. The + default value is `true`, which means the watch is active by default. + +[float] +==== Request Body + +A watch has the following fields: + +[options="header"] +|====== +| Name | Description + +| `trigger` | The {xpack-ref}/trigger.html[trigger] that defines when + the watch should run. + +| `input` | The {xpack-ref}/input.html[input] that defines the input + that loads the data for the watch. + +| `condition` | The {xpack-ref}/condition.html[condition] that defines if + the actions should be run. + +| `actions` | The list of {xpack-ref}/actions.html[actions] that will be + run if the condition matches + +| `metadata` | Metadata json that will be copied into the history entries. + +| `throttle_period` | The minimum time between actions being run, the default + for this is 5 seconds. This default can be changed in the + config file with the setting `xpack.watcher.throttle.period.default_period`. +|====== + +[float] +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + The following example adds a watch with the `my-watch` id that has the following characteristics: @@ -72,39 +136,10 @@ PUT _xpack/watcher/watch/my-watch -------------------------------------------------- // CONSOLE -A watch has the following fields: - -[options="header"] -|====== -| Name | Description - -| `trigger` | The {xpack-ref}/trigger.html[trigger] that defines when - the watch should run. - -| `input` | The {xpack-ref}/input.html[input] that defines the input - that loads the data for the watch. - -| `condition` | The {xpack-ref}/condition.html[condition] that defines if - the actions should be run. - -| `actions` | The list of {xpack-ref}/actions.html[actions] that will be - run if the condition matches - -| `metadata` | Metadata json that will be copied into the history entries. - -| `throttle_period` | The minimum time between actions being run, the default - for this is 5 seconds. This default can be changed in the - config file with the setting `xpack.watcher.throttle.period.default_period`. -|====== - -[float] -[[watcher-api-put-watch-active-state]] -==== Controlling Default Active State - -When adding a watch you can also define its initial +When you add a watch you can also define its initial {xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that -by setting the `active` parameter. The following command add a watch and sets it -to be inactive by default: +by setting the `active` parameter. The following command adds a watch and sets +it to be inactive by default: [source,js] -------------------------------------------------- diff --git a/docs/en/rest-api/watcher/start.asciidoc b/docs/en/rest-api/watcher/start.asciidoc index 432d5b385a8..ffdec3326d5 100644 --- a/docs/en/rest-api/watcher/start.asciidoc +++ b/docs/en/rest-api/watcher/start.asciidoc @@ -3,7 +3,20 @@ === Start API The `start` API starts the {watcher} service if the service is not already -running, as in the following example: +running. + +[float] +==== Request + +`POST _xpack/watcher/_start` + +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples [source,js] -------------------------------------------------- diff --git a/docs/en/rest-api/watcher/stats.asciidoc b/docs/en/rest-api/watcher/stats.asciidoc index a714b76f09a..38f8ede925e 100644 --- a/docs/en/rest-api/watcher/stats.asciidoc +++ b/docs/en/rest-api/watcher/stats.asciidoc @@ -2,22 +2,70 @@ [[watcher-api-stats]] === Stats API -The `stats` API returns the current {watcher} metrics. You can control what -metrics this API returns using the `metric` parameter. +The `stats` API returns the current {watcher} metrics. -The supported metrics are: +[float] +==== Request -[options="header"] -|====== -| Metric | Description -| `executing_watches` | Include the current executing watches in the response. -| `queued_watches` | Include the watches queued for execution in the response. -| `_all` | Include all metrics in the response. -|====== +`GET _xpack/watcher/stats` + -The {watcher} `stats` API always returns basic metrics regardless of the -`metric` option. The following example calls the `stats` API including the -basic metrics: +`GET _xpack/watcher/stats/` + +[float] +==== Description + +This API always returns basic metrics. You retrieve more metrics by using +the `metric` parameter. + +[float] +===== Current executing watches metric + +The current executing watches metric gives insight into the watches that are +currently being executed by {watcher}. Additional information is shared per +watch that is currently executing. This information includes the `watch_id`, +the time its execution started and its current execution phase. + +To include this metric, the `metric` option should be set to `executing_watches` +or `_all`. In addition you can also specify the `emit_stacktraces=true` +parameter, which adds stack traces for each watch that is being executed. These +stack traces can give you more insight into an execution of a watch. + +[float] +===== Queued watches metric + +{watcher} moderates the execution of watches such that their execution won't put +too much pressure on the node and its resources. If too many watches trigger +concurrently and there isn't enough capacity to execute them all, some of the +watches are queued, waiting for the current executing watches to finish their +execution. The queued watches metric gives insight on these queued watches. + +To include this metric, the `metric` option should include `queued_watches` or +`_all`. + +[float] +==== Path Parameters + +`emit_stacktraces`:: + (boolean) Defines whether stack traces are generated for each watch that is + running. The default value is `false`. + +`metric`:: + (enum) Defines which additional metrics are included in the response. + `executing_watches`::: Includes the current executing watches in the response. + `queued_watches`::: Includes the watches queued for execution in the response. + `_all`::: Includes all metrics in the response. + +[float] +==== Authorization + +You must have `manage_watcher` or `monitor_watcher` cluster privileges to use +this API. For more information, see +{xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples + +The following example calls the `stats` API to retrieve basic metrics: [source,js] -------------------------------------------------- @@ -39,21 +87,11 @@ A successful call returns a JSON structure similar to the following example: } -------------------------------------------------- -<1> The current state of watcher. May be either `started`, `starting` or `stopped`. +<1> The current state of watcher, which can be `started`, `starting`, or `stopped`. <2> The number of watches currently registered. <3> The number of watches that were triggered and currently queued for execution. -<4> The largest size of the execution thread pool indicating the largest number - of concurrent executing watches. - -==== Current executing watches metric - -The current executing watches metric gives insight into the watches that are -currently being executed by {watcher}. Additional information is shared per -watch that is currently executing. This information includes the `watch_id`, -the time its execution started and its current execution phase. - -To include this metric, the `metric` option should be set to `executing_watches` -or `_all`. +<4> The largest size of the execution thread pool, which indicates the largest +number of concurrent executing watches. The following example specifies the `metric` option as a query string argument and will include the basic metrics and metrics about the current executing watches: @@ -96,8 +134,8 @@ captures a watch in execution: } -------------------------------------------------- -<1> A list of all the Watches that are currently being executed by {watcher}. - When no watches are currently executing an empty array is returned. The +<1> A list of all the watches that are currently being executed by {watcher}. + When no watches are currently executing, an empty array is returned. The captured watches are sorted by execution time in descending order. Thus the longest running watch is always at the top. <2> The id of the watch being executed. @@ -108,21 +146,6 @@ captures a watch in execution: <6> The current watch execution phase. Can be `input`, `condition` `actions`, `awaits_execution`, `started`, `watch_transform`, `aborted`, `finished`. -In addition you can also specify the `emit_stacktraces=true` parameter, which -adds stack traces for each watch that is being executed. These stacktraces can -give you more insight into an execution of a watch. - -==== Queued watches metric - -{watcher} moderates the execution of watches such that their execution won't put -too much pressure on the node and its resources. If too many watches trigger -concurrently and there isn't enough capacity to execute them all, some of the -watches are queued, waiting for the current executing watches to finish their -execution. The queued watches metric gives insight on these queued watches. - -To include this metric, the `metric` option should include `queued_watches` or -`_all`. - The following example specifies the `queued_watches` metric option and includes both the basic metrics and the queued watches: diff --git a/docs/en/rest-api/watcher/stop.asciidoc b/docs/en/rest-api/watcher/stop.asciidoc index 30bc99c7cc1..11345c89cef 100644 --- a/docs/en/rest-api/watcher/stop.asciidoc +++ b/docs/en/rest-api/watcher/stop.asciidoc @@ -2,8 +2,21 @@ [[watcher-api-stop]] === Stop API -The `stop` API stops the {watcher} service if the service is running, as in the -following example: +The `stop` API stops the {watcher} service if the service is running. + +[float] +==== Request + +`POST _xpack/watcher/_stop` + +[float] +==== Authorization + +You must have `manage_watcher` cluster privileges to use this API. For more +information, see {xpack-ref}/security-privileges.html[Security Privileges]. + +[float] +==== Examples [source,js] --------------------------------------------------