honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Reformats Watcher APIs using template (#46152)

This commit is contained in:
Lisa Cawley 2019-09-05 11:19:35 -07:00 committed by lcawl
parent af1516a377
commit 9f1339d0ce
10 changed files with 326 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc
View File

@ -6,40 +6,55 @@
++++
{stack-ov}/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.<id>.ack.state`
structure.
to manually throttle execution of the watch's actions.
IMPORTANT: If the specified watch is currently being executed, this API will return
an error. The reason for this is to prevent overwriting of the watch status from a watch
execution.
[float]
==== Request
[[watcher-api-ack-watch-request]]
==== {api-request-title}
`PUT _watcher/watch/<watch_id>/_ack` +
`PUT _watcher/watch/<watch_id>/_ack/<action_id>`
[float]
==== Path Parameters
[[watcher-api-ack-watch-prereqs]]
==== {api-prereq-title}
`action_id`::
(list) A comma-separated list of the action IDs to acknowledge. If you omit
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[[watcher-api-ack-watch-desc]]
==== {api-description-title}
An action's _acknowledgement state_ is stored in the
`status.actions.<id>.ack.state` structure.
IMPORTANT: If the specified watch is currently being executed, this API will
return an error. The reason for this is to prevent overwriting of the watch
status from a watch execution.
[[watcher-api-ack-watch-path-params]]
==== {api-path-parms-title}
`<action_id>`::
(Optional, 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.
`<watch_id>`::
(Required, string) Identifier for the watch.
[float]
==== Authorization
//[[watcher-api-ack-watch-query-params]]
//==== {api-query-parms-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
//[[watcher-api-ack-watch-request-body]]
//==== {api-request-body-title}
//[[watcher-api-ack-watch-response-body]]
//==== {api-response-body-title}
[float]
==== Examples
//[[watcher-api-ack-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-ack-watch-example]]
==== {api-examples-title}
To demonstrate let's create a new watch:

41
x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc
View File

@ -9,28 +9,43 @@ A watch can be either
{stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This
API enables you to activate a currently inactive watch.
[float]
==== Request
[[watcher-api-activate-watch-request]]
==== {api-request-title}
`PUT _watcher/watch/<watch_id>/_activate`
[float]
==== Path Parameters
[[watcher-api-activate-watch-prereqs]]
==== {api-prereq-title}
`watch_id` (required)::
(string) Identifier for the watch.
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[float]
==== Authorization
//[[watcher-api-activate-watch-desc]]
//==== {api-description-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
[[watcher-api-activate-watch-path-params]]
==== {api-path-parms-title}
[float]
==== Examples
`<watch_id>`::
(Required, string) Identifier for the watch.
//[[watcher-api-activate-watch-query-params]]
//==== {api-query-parms-title}
//[[watcher-api-activate-watch-request-body]]
//==== {api-request-body-title}
//[[watcher-api-activate-watch-response-body]]
//==== {api-response-body-title}
//[[watcher-api-activate-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-activate-watch-example]]
==== {api-examples-title}
The status of an inactive watch is returned with the watch definition when you
call the <<watcher-api-get-watch, Get Watch API>>:
call the <<watcher-api-get-watch,get watch API>>:
[source,js]
--------------------------------------------------

42
x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc
View File

@ -9,27 +9,43 @@ A watch can be either
{stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This
API enables you to deactivate a currently active watch.
[float]
==== Request
[[watcher-api-deactivate-watch-request]]
==== {api-request-title}
`PUT _watcher/watch/<watch_id>/_deactivate`
[float]
==== Path Parameters
[[watcher-api-deactivate-watch-prereqs]]
==== {api-prereq-title}
`watch_id` (required)::
(string) Identifier for the watch.
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[float]
==== Authorization
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
//[[watcher-api-deactivate-watch-desc]]
//==== {api-description-title}
[float]
==== Examples
[[watcher-api-deactivate-watch-path-params]]
==== {api-path-parms-title}
`<watch_id>`::
(Required, string) Identifier for the watch.
//[[watcher-api-deactivate-watch-query-params]]
//==== {api-query-parms-title}
//[[watcher-api-deactivate-watch-request-body]]
//==== {api-request-body-title}
//[[watcher-api-deactivate-watch-response-body]]
//==== {api-response-body-title}
//[[watcher-api-deactivate-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-deactivate-watch-example]]
==== {api-examples-title}
The status of an active watch is returned with the watch definition when you
call the <<watcher-api-get-watch, Get Watch API>>:
call the <<watcher-api-get-watch,get watch API>>:
[source,js]
--------------------------------------------------

42
x-pack/docs/en/rest-api/watcher/delete-watch.asciidoc
View File

@ -5,15 +5,21 @@
<titleabbrev>Delete watch</titleabbrev>
++++
The delete watch API removes a watch from {watcher}.
Removes a watch from {watcher}.
[float]
==== Request
[[watcher-api-delete-watch-request]]
==== {api-request-title}
`DELETE _watcher/watch/<watch_id>`
[float]
==== Description
[[watcher-api-delete-watch-prereqs]]
==== {api-prereq-title}
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[[watcher-api-delete-watch-desc]]
==== {api-description-title}
When the watch is removed, the document representing the watch in the `.watches`
index is gone and it will never be run again.
@ -27,20 +33,26 @@ IMPORTANT: Deleting a watch must be done via this API only. Do not delete the
sure no `write` privileges are granted to anyone over the `.watches`
index.
[float]
==== Path Parameters
[[watcher-api-delete-watch-path-params]]
==== {api-path-parms-title}
`watch_id` (required)::
(string) Identifier for the watch.
`<watch_id>`::
(Required, string) Identifier for the watch.
[float]
==== Authorization
//[[watcher-api-delete-watch-query-params]]
//==== {api-query-parms-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
//[[watcher-api-delete-watch-request-body]]
//==== {api-request-body-title}
[float]
==== Examples
//[[watcher-api-delete-watch-response-body]]
//==== {api-response-body-title}
//[[watcher-api-delete-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-delete-watch-example]]
==== {api-examples-title}
The following example deletes a watch with the `my-watch` id:

68
x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc
View File

@ -5,19 +5,26 @@
<titleabbrev>Execute watch</titleabbrev>
++++
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.
Forces the execution of a stored watch.
[float]
==== Request
[[watcher-api-execute-watch-request]]
==== {api-request-title}
`POST _watcher/watch/<watch_id>/_execute` +
`POST _watcher/watch/_execute`
[float]
==== Description
[[watcher-api-execute-watch-prereqs]]
==== {api-prereq-title}
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[[watcher-api-execute-watch-desc]]
==== {api-description-title}
This API can be used to force execution of the watch outside of its triggering
logic or to simulate the watch execution for debugging purposes.
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
@ -25,29 +32,28 @@ 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
===== 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
[[watcher-api-execute-watch-path-params]]
==== {api-path-parms-title}
`watch_id`::
(string) Identifier for the watch.
`<watch_id>`::
(Optional, string) Identifier for the watch.
[float]
==== Query Parameters
[[watcher-api-execute-watch-query-params]]
==== {api-query-parms-title}
`debug`::
(boolean) Defines whether the watch runs in debug mode. The default value is
`false`.
(Optional, boolean) Defines whether the watch runs in debug mode. The default
value is `false`.
[float]
==== Request Body
[[watcher-api-execute-watch-request-body]]
==== {api-request-body-title}
This API supports the following fields:
@ -59,7 +65,7 @@ This API supports the following fields:
that will be used during the watch execution
| `ignore_condition` | no | false | When set to `true`, the watch execution uses the
{stack-ov}/condition-always.html[Always Condition].
{stack-ov}/condition-always.html[Always condition].
This can also be specified as an HTTP parameter.
| `alternative_input` | no | null | When present, the watch uses this object as a payload
@ -81,9 +87,8 @@ 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 execution modes
Action modes define how actions are handled during the watch execution. There
are five possible modes an action can be associated with:
@ -116,13 +121,8 @@ are five possible modes an action can be associated with:
Effectively forces the action to be throttled.
|======
[float]
==== Authorization
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security Privileges].
[float]
==== Security Integration
[[watcher-api-execute-watch-security]]
===== Security integration
When {es} {security-features} are enabled on your cluster, watches
are executed with the privileges of the user that stored the watches. If your
@ -133,8 +133,14 @@ When using the execute watch API, the authorization data of the user that
called the API will be used as a base, instead of of the information who stored
the watch.
[float]
==== Examples
//[[watcher-api-execute-watch-response-body]]
//==== {api-response-body-title}
//[[watcher-api-execute-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-execute-watch-example]]
==== {api-examples-title}
The following example executes the `my_watch` watch:

45
x-pack/docs/en/rest-api/watcher/get-watch.asciidoc
View File

@ -5,28 +5,43 @@
<titleabbrev>Get watch</titleabbrev>
++++
This API retrieves a watch by its ID.
Retrieves a watch by its ID.
[float]
==== Request
[[watcher-api-get-watch-request]]
==== {api-request-title}
`GET _watcher/watch/<watch_id>`
[float]
==== Path Parameters
[[watcher-api-get-watch-prereqs]]
==== {api-prereq-title}
`watch_id` (required)::
(string) Identifier for the watch.
[float]
==== Authorization
You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
* 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].
{stack-ov}/security-privileges.html[Security privileges].
[float]
==== Examples
//[[watcher-api-get-watch-desc]]
//==== {api-description-title}
[[watcher-api-get-watch-path-params]]
==== {api-path-parms-title}
`<watch_id>`::
(Required, string) Identifier for the watch.
//[[watcher-api-get-watch-query-params]]
//==== {api-query-parms-title}
//[[watcher-api-get-watch-request-body]]
//==== {api-request-body-title}
//[[watcher-api-get-watch-response-body]]
//==== {api-response-body-title}
//[[watcher-api-get-watch-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-get-watch-example]]
==== {api-examples-title}
The following example gets a watch with `my-watch` id:

65
x-pack/docs/en/rest-api/watcher/put-watch.asciidoc
View File

@ -5,16 +5,21 @@
<titleabbrev>Put watch</titleabbrev>
++++
The PUT watch API either registers a new watch in {watcher} or updates an
existing one.
Either registers a new watch in {watcher} or updates an existing one.
[float]
==== Request
[[watcher-api-put-watch-request]]
==== {api-request-title}
`PUT _watcher/watch/<watch_id>`
[float]
==== Description
[[watcher-api-put-watch-prereqs]]
==== {api-prereq-title}
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[[watcher-api-put-watch-desc]]
==== {api-description-title}
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
@ -30,21 +35,29 @@ When adding a watch you can also define its initial
{stack-ov}/how-watcher-works.html#watch-active-state[active state]. You do that
by setting the `active` parameter.
[float]
==== Path Parameters
[[watcher-api-put-watch-security]]
===== Security integration
`watch_id` (required)::
(string) Identifier for the watch.
When {es} {security-features} are enabled, your watch can index or search only
on indices for which the user that stored the watch has privileges. If the user
is able to read index `a`, but not index `b`, the same will apply, when the watch
is executed.
[float]
==== Query Parameters
[[watcher-api-put-watch-path-params]]
==== {api-path-parms-title}
`<watch_id>`::
(Required, string) Identifier for the watch.
[[watcher-api-put-watch-query-params]]
==== {api-query-parms-title}
`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.
(Optional, 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
[[watcher-api-put-watch-request-body]]
==== {api-request-body-title}
A watch has the following fields:
@ -82,22 +95,14 @@ A watch has the following fields:
|======
[float]
==== Authorization
//[[watcher-api-put-watch-response-body]]
//==== {api-response-body-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security Privileges].
//[[watcher-api-put-watch-response-codes]]
//==== {api-response-codes-title}
[float]
==== Security Integration
When {es} {security-features} are enabled, your watch can index or search only
on indices for which the user that stored the watch has privileges. If the user
is able to read index `a`, but not index `b`, the same will apply, when the watch
is executed.
[float]
==== Examples
[[watcher-api-put-watch-example]]
==== {api-examples-title}
The following example adds a watch with the `my-watch` id that has the following
characteristics:

33
x-pack/docs/en/rest-api/watcher/start.asciidoc
View File

@ -7,18 +7,37 @@
Starts the {watcher} service if it is not already running.
[float]
==== Request
[[watcher-api-start-request]]
==== {api-request-title}
`POST _watcher/_start`
==== Authorization
[[watcher-api-start-prereqs]]
==== {api-prereq-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[float]
==== Examples
//[[watcher-api-start-desc]]
//==== {api-description-title}
//[[watcher-api-start-path-params]]
//==== {api-path-parms-title}
//[[watcher-api-start-query-params]]
//==== {api-query-parms-title}
//[[watcher-api-start-request-body]]
//==== {api-request-body-title}
//[[watcher-api-start-response-body]]
//==== {api-response-body-title}
//[[watcher-api-start-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-start-example]]
==== {api-examples-title}
[source,js]
--------------------------------------------------

95
x-pack/docs/en/rest-api/watcher/stats.asciidoc
View File

@ -8,66 +8,75 @@
Retrieves the current {watcher} metrics.
[float]
==== Request
[[watcher-api-stats-request]]
==== {api-request-title}
`GET _watcher/stats` +
`GET _watcher/stats/<metric>`
[float]
==== Description
[[watcher-api-stats-prereqs]]
==== {api-prereq-title}
This API always returns basic metrics. You retrieve more metrics by using
the `metric` parameter.
* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
this API. For more information, see
{stack-ov}/security-privileges.html[Security privileges].
[float]
===== Current executing watches metric
//[[watcher-api-stats-desc]]
//==== {api-description-title}
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 `current_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
[[watcher-api-stats-path-params]]
==== {api-path-parms-title}
`emit_stacktraces`::
(boolean) Defines whether stack traces are generated for each watch that is
running. The default value is `false`.
(Optional, 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.
`<metric>`::
(Optional, enum) Defines which additional metrics are included in the response.
`current_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
//[[watcher-api-stats-query-params]]
//==== {api-query-parms-title}
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].
//[[watcher-api-stats-request-body]]
//==== {api-request-body-title}
[float]
==== Examples
[[watcher-api-stats-response-body]]
==== {api-response-body-title}
This API always returns basic metrics. You retrieve more metrics by using
the `metric` parameter.
`current_watches`::
(list) 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 `current_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.
`queued_watches`::
(list) {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`.
//[[watcher-api-stats-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-stats-example]]
==== {api-examples-title}
The following example calls the `stats` API to retrieve basic metrics:

34
x-pack/docs/en/rest-api/watcher/stop.asciidoc
View File

@ -7,19 +7,37 @@
Stops the {watcher} service if it is running.
[float]
==== Request
[[watcher-api-stop-request]]
==== {api-request-title}
`POST _watcher/_stop`
[float]
==== Authorization
[[watcher-api-stop-prereqs]]
==== {api-prereq-title}
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {xpack-ref}/security-privileges.html[Security Privileges].
* You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security privileges].
[float]
==== Examples
//[[watcher-api-stop-desc]]
//==== {api-description-title}
//[[watcher-api-stop-path-params]]
//==== {api-path-parms-title}
//[[watcher-api-stop-query-params]]
//==== {api-query-parms-title}
//[[watcher-api-stop-request-body]]
//==== {api-request-body-title}
//[[watcher-api-stop-response-body]]
//==== {api-response-body-title}
//[[watcher-api-stop-response-codes]]
//==== {api-response-codes-title}
[[watcher-api-stop-example]]
==== {api-examples-title}
[source,js]
--------------------------------------------------