From 8fc5aadec9bc74038ae6630168d215d39ff30831 Mon Sep 17 00:00:00 2001 From: lcawley Date: Wed, 29 Mar 2017 09:07:55 -0700 Subject: [PATCH] [DOCS] Add watcher rest-api docs to x-pack-elasticsearch Original commit: elastic/x-pack-elasticsearch@a1cb3755998a64a545ee5b8a7b0ebde89115f7c6 --- docs/public/rest-api/ml.asciidoc | 20 ++ docs/public/rest-api/watcher.asciidoc | 26 ++ .../rest-api/watcher/ack-watch.asciidoc | 224 ++++++++++++ .../rest-api/watcher/activate-watch.asciidoc | 64 ++++ .../watcher/deactivate-watch.asciidoc | 64 ++++ .../rest-api/watcher/delete-watch.asciidoc | 55 +++ .../rest-api/watcher/execute-watch.asciidoc | 335 ++++++++++++++++++ .../rest-api/watcher/get-watch.asciidoc | 67 ++++ .../rest-api/watcher/put-watch.asciidoc | 128 +++++++ docs/public/rest-api/watcher/restart.asciidoc | 21 ++ docs/public/rest-api/watcher/start.asciidoc | 21 ++ docs/public/rest-api/watcher/stats.asciidoc | 161 +++++++++ docs/public/rest-api/watcher/stop.asciidoc | 21 ++ 13 files changed, 1207 insertions(+) create mode 100644 docs/public/rest-api/ml.asciidoc create mode 100644 docs/public/rest-api/watcher.asciidoc create mode 100644 docs/public/rest-api/watcher/ack-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/activate-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/deactivate-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/delete-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/execute-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/get-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/put-watch.asciidoc create mode 100644 docs/public/rest-api/watcher/restart.asciidoc create mode 100644 docs/public/rest-api/watcher/start.asciidoc create mode 100644 docs/public/rest-api/watcher/stats.asciidoc create mode 100644 docs/public/rest-api/watcher/stop.asciidoc diff --git a/docs/public/rest-api/ml.asciidoc b/docs/public/rest-api/ml.asciidoc new file mode 100644 index 00000000000..2ff53b2c7a4 --- /dev/null +++ b/docs/public/rest-api/ml.asciidoc @@ -0,0 +1,20 @@ +[[ml-api]] +== Machine Learning APIs + +Use machine learning to detect anomalies in time series data. + +//=== Job Management APIs +//* <> +//* <> +//* <> +//* <> +//* <> +//* <> + + +//include::ml/put-job.asciidoc[] +//include::ml/delete-job.asciidoc[] +//include::ml/get-job.asciidoc[] +//include::ml/open-close-job.asciidoc[] +//include::ml/flush-job.asciidoc[] +//include::ml/post-data.asciidoc[] diff --git a/docs/public/rest-api/watcher.asciidoc b/docs/public/rest-api/watcher.asciidoc new file mode 100644 index 00000000000..a9dbe0bce9e --- /dev/null +++ b/docs/public/rest-api/watcher.asciidoc @@ -0,0 +1,26 @@ +[[watcher-api]] +== Watcher APIs + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +include::watcher/put-watch.asciidoc[] +include::watcher/get-watch.asciidoc[] +include::watcher/delete-watch.asciidoc[] +include::watcher/execute-watch.asciidoc[] +include::watcher/ack-watch.asciidoc[] +include::watcher/activate-watch.asciidoc[] +include::watcher/deactivate-watch.asciidoc[] +include::watcher/stats.asciidoc[] +include::watcher/stop.asciidoc[] +include::watcher/start.asciidoc[] +include::watcher/restart.asciidoc[] diff --git a/docs/public/rest-api/watcher/ack-watch.asciidoc b/docs/public/rest-api/watcher/ack-watch.asciidoc new file mode 100644 index 00000000000..17e628230b1 --- /dev/null +++ b/docs/public/rest-api/watcher/ack-watch.asciidoc @@ -0,0 +1,224 @@ +[[watcher-api-ack-watch]] +=== Ack Watch API + +<> 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. + +To demonstrate let's create a new watch: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my_watch +{ + "trigger": { + "schedule": { + "hourly": { + "minute": [ 0, 5 ] + } + } + }, + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "actions": { + "test_index": { + "throttle_period": "15m", + "index": { + "index": "test", + "doc_type": "test2" + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TESTSETUP + +The current status of a watch and the state of its actions is returned with the +watch definition when you call the <>: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE + +The action state of a newly-created watch is `awaits_successful_execution`: + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { + "version": 1, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:04:27.723Z", + "state": "awaits_successful_execution" + } + } + }, + "state": ... + }, + "watch": ... +} +-------------------------------------------------- +// TESTRESPONSE[s/"state": \.\.\./"state": "$body._status.state"/] +// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/] +// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body._status.actions.test_index.ack.timestamp"/] + +When the watch executes and the condition matches, the value of the `ack.state` +changes to `ackable`. Let's force execution of the watch and fetch it again to +check the status: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// TEST[continued] + +and the action is now in `ackable` state: + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { + "version": 1, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:04:27.723Z", + "state": "ackable" + } + } + }, + "state": ... + }, + "watch": ... +} +-------------------------------------------------- +// TESTRESPONSE[s/"state": \.\.\./"state": "$body._status.state"/] +// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/] +// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body._status.actions.test_index.ack.timestamp"/] + +Now we can acknowledge it: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my_watch/_ack/test_index +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { + "version": 1, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:04:27.723Z", + "state": "acknowledged" + } + } + }, + "state": ... + }, + "watch": ... +} +-------------------------------------------------- +// TESTRESPONSE[s/"state": \.\.\./"state": "$body._status.state"/] +// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/] +// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body._status.actions.test_index.ack.timestamp"/] + +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`). + +You can acknowledge multiple actions by assigning the `actions` parameter a +comma-separated list of action ids: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_ack/action1,action2 +-------------------------------------------------- +// CONSOLE + +To acknowledge all of the actions of a watch, simply omit the `actions` +parameter: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_ack +-------------------------------------------------- +// CONSOLE + +[float] +==== Timeouts + +If you acknowledge a watch while it is executing, the request blocks and waits +for the watch execution to finish. For some watches, this can take a significant +amount of time. By default, the acknowledge action has a timeout of 10 seconds. +You can change the timeout setting by specifying the `master_timeout` parameter. + +The following snippet shows how to change the default timeout of the acknowledge +action to 30 seconds: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_ack?master_timeout=30s +-------------------------------------------------- +// CONSOLE + +[float] +==== Response format +[source,js] + +The response format looks like: + +[source,js] +-------------------------------------------------- +{ + "_status": { + "last_checked": "2015-05-26T18:21:08.630Z", + "last_met_condition": "2015-05-26T18:21:08.630Z", + "actions": { + "my-action": { + "ack_status": { + "timestamp": "2015-05-26T18:21:09.982Z", + "state": "acked" + }, + "last_execution": { + "timestamp": "2015-05-26T18:21:04.106Z", + "successful": true + }, + "last_successful_execution": { + "timestamp": "2015-05-26T18:21:04.106Z", + "successful": true + }, + "last_throttle": { + "timestamp": "2015-05-26T18:21:08.630Z", + "reason": "throttling interval is set to [5 seconds] but time elapsed since last execution is [4 seconds and 530 milliseconds]" + } + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/public/rest-api/watcher/activate-watch.asciidoc b/docs/public/rest-api/watcher/activate-watch.asciidoc new file mode 100644 index 00000000000..1564b681892 --- /dev/null +++ b/docs/public/rest-api/watcher/activate-watch.asciidoc @@ -0,0 +1,64 @@ +[[watcher-api-activate-watch]] +=== Activate Watch API + +A watch can be either <>. This API enables +you to activate a currently inactive watch. + +The status of an inactive watch is returned with the watch definition when you +call the <>: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_inactive_watch] + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { + "state" : { + "active" : false, + "timestamp" : "2015-08-20T12:21:32.734Z" + }, + "actions": ..., + "version": 1 + }, + "watch": ... +} +-------------------------------------------------- +// TESTRESPONSE[s/2015-08-20T12:21:32.734Z/$body._status.state.timestamp/] +// TESTRESPONSE[s/"actions": \.\.\./"actions": "$body._status.actions"/] +// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/] +// TESTRESPONSE[s/"version": 1/"version": $body._status.version/] + +You can activate the watch by executing the following API call: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my_watch/_activate +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_inactive_watch] + +The new state of the watch is returned as part of its overall status: + +[source,js] +-------------------------------------------------- +{ + "_status": { + "state" : { + "active" : true, + "timestamp" : "2015-09-04T08:39:46.816Z" + }, + "actions": ..., + "version": 1 + } +} +-------------------------------------------------- +// TESTRESPONSE[s/2015-09-04T08:39:46.816Z/$body._status.state.timestamp/] +// TESTRESPONSE[s/"actions": \.\.\./"actions": "$body._status.actions"/] +// TESTRESPONSE[s/"version": 1/"version": $body._status.version/] diff --git a/docs/public/rest-api/watcher/deactivate-watch.asciidoc b/docs/public/rest-api/watcher/deactivate-watch.asciidoc new file mode 100644 index 00000000000..6aaed843598 --- /dev/null +++ b/docs/public/rest-api/watcher/deactivate-watch.asciidoc @@ -0,0 +1,64 @@ +[[watcher-api-deactivate-watch]] +=== Deactivate Watch API + +A watch can be either <>. This API +enables you to deactivate a currently active watch. + +The status of an active watch is returned with the watch definition when you +call the <>: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { + "state" : { + "active" : true, + "timestamp" : "2015-08-20T12:21:32.734Z" + }, + "actions": ..., + "version": 1 + }, + "watch": ... +} +-------------------------------------------------- +// TESTRESPONSE[s/2015-08-20T12:21:32.734Z/$body._status.state.timestamp/] +// TESTRESPONSE[s/"actions": \.\.\./"actions": "$body._status.actions"/] +// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/] +// TESTRESPONSE[s/"version": 1/"version": $body._status.version/] + +You can deactivate the watch by executing the following API call: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my_watch/_deactivate +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +The new state of the watch is returned as part of its overall status: + +[source,js] +-------------------------------------------------- +{ + "_status": { + "state" : { + "active" : false, + "timestamp" : "2015-09-04T08:39:46.816Z" + }, + "actions": ..., + "version": 1 + } +} +-------------------------------------------------- +// TESTRESPONSE[s/2015-09-04T08:39:46.816Z/$body._status.state.timestamp/] +// TESTRESPONSE[s/"actions": \.\.\./"actions": "$body._status.actions"/] +// TESTRESPONSE[s/"version": 1/"version": $body._status.version/] diff --git a/docs/public/rest-api/watcher/delete-watch.asciidoc b/docs/public/rest-api/watcher/delete-watch.asciidoc new file mode 100644 index 00000000000..0e79828bdc4 --- /dev/null +++ b/docs/public/rest-api/watcher/delete-watch.asciidoc @@ -0,0 +1,55 @@ +[[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. + +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 + DELETE Document API. When {security} is enabled, make sure no `write` + privileges are granted to anyone over the `.watches` index. + +The following example deletes a watch with the `my-watch` id: + +[source,js] +-------------------------------------------------- +DELETE _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +Response: + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_version": 2 +} +-------------------------------------------------- +// TESTRESPONSE + +[float] +==== Timeouts + +When deleting a watch while it is executing, the delete action will block and +wait for the watch execution to finish. Depending on the nature of the watch, in +some situations this can take a while. For this reason, the delete watch action +is associated with a timeout that is set to 10 seconds by default. You can +control this timeout by passing in the `master_timeout` parameter. + +The following snippet shows how to change the default timeout of the delete +action to 30 seconds: + +[source,js] +-------------------------------------------------- +DELETE _xpack/watcher/watch/my_watch?master_timeout=30s +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + diff --git a/docs/public/rest-api/watcher/execute-watch.asciidoc b/docs/public/rest-api/watcher/execute-watch.asciidoc new file mode 100644 index 00000000000..f063bedebe9 --- /dev/null +++ b/docs/public/rest-api/watcher/execute-watch.asciidoc @@ -0,0 +1,335 @@ +[[watcher-api-execute-watch]] +=== Execute Watch API + +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: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +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. + +This API supports the following fields: + +[cols=",^,^,", options="header"] +|====== +| Name | Required | Default | Description + +| `trigger_data` | no | | This structure is parsed as the data of the trigger event + that will be used during the watch execution + +| `ignore_condition` | no | false | When set to `true`, the watch execution uses the + <> Condition. This can also be + specified as a HTTP parameter. + +| `alternative_input` | no | null | When present, the watch uses this object as a payload + instead of executing its own input. + +| `action_modes` | no | null | Determines how to handle the watch actions as part of the + watch execution. See <> + for more information. + +| `record_execution` | no | false | 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 a HTTP parameter. + +| `watch` | no | null | When present, this <> is used + instead of the one specified in the request. This watch is + not persisted to the index and record_execution cannot be set. +|====== + +The following example shows a comprehensive example of executing the `my-watch` watch: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +{ + "trigger_data" : { <1> + "triggered_time" : "now", + "scheduled_time" : "now" + }, + "alternative_input" : { <2> + "foo" : "bar" + }, + "ignore_condition" : true, <3> + "action_modes" : { + "my-action" : "force_simulate" <4> + }, + "record_execution" : true <5> +} +-------------------------------------------------- +// CONSOLE +// 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 + 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. + +This is an example of the output: + +[source,js] +-------------------------------------------------- +{ + "_id": "my_watch_0-2015-06-02T23:17:55.124Z", <1> + "watch_record": { <2> + "watch_id": "my_watch", + "messages": [], + "trigger_event": { + "type": "manual", + "triggered_time": "2015-06-02T23:17:55.124Z", + "manual": { + "schedule": { + "scheduled_time": "2015-06-02T23:17:55.124Z" + } + } + }, + "state": "executed", + "_status": { + "version": 1, + "state": { + "active": true, + "timestamp": "2015-06-02T23:17:55.111Z" + }, + "last_checked": "2015-06-02T23:17:55.124Z", + "last_met_condition": "2015-06-02T23:17:55.124Z", + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-06-02T23:17:55.124Z", + "state": "ackable" + }, + "last_execution": { + "timestamp": "2015-06-02T23:17:55.124Z", + "successful": true + }, + "last_successful_execution": { + "timestamp": "2015-06-02T23:17:55.124Z", + "successful": true + } + } + } + }, + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "result": { <3> + "execution_time": "2015-06-02T23:17:55.124Z", + "execution_duration": 12608, + "input": { + "type": "simple", + "payload": { + "foo": "bar" + }, + "status": "success" + }, + "condition": { + "type": "always", + "met": true, + "status": "success" + }, + "actions": [ + { + "id": "test_index", + "index": { + "response": { + "index": "test", + "type": "test2", + "version": 1, + "created": true, + "result": "created", + "id": "AVSHKzPa9zx62AzUzFXY" + } + }, + "status": "success", + "type": "index" + } + ] + } + } +} +-------------------------------------------------- +// TESTRESPONSE[s/my_watch_0-2015-06-02T23:17:55.124Z/$body._id/] +// TESTRESPONSE[s/"triggered_time": "2015-06-02T23:17:55.124Z"/"triggered_time": "$body.watch_record.trigger_event.triggered_time"/] +// TESTRESPONSE[s/"scheduled_time": "2015-06-02T23:17:55.124Z"/"scheduled_time": "$body.watch_record.trigger_event.manual.schedule.scheduled_time"/] +// TESTRESPONSE[s/"execution_time": "2015-06-02T23:17:55.124Z"/"execution_time": "$body.watch_record.result.execution_time"/] +// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.111Z"/"timestamp": "$body.watch_record._status.state.timestamp"/] +// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.124Z"/"timestamp": "$body.watch_record._status.actions.test_index.ack.timestamp"/] +// TESTRESPONSE[s/"last_checked": "2015-06-02T23:17:55.124Z"/"last_checked": "$body.watch_record._status.last_checked"/] +// TESTRESPONSE[s/"last_met_condition": "2015-06-02T23:17:55.124Z"/"last_met_condition": "$body.watch_record._status.last_met_condition"/] +// TESTRESPONSE[s/"execution_duration": 12608/"execution_duration": "$body.watch_record.result.execution_duration"/] +// TESTRESPONSE[s/"id": "AVSHKzPa9zx62AzUzFXY"/"id": "$body.watch_record.result.actions.0.index.response.id"/] +<1> The id of the watch record as it would be stored in the `.watcher-history` index. +<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 + <> 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: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +{ + "action_modes" : { + "action1" : "force_simulate", + "action2" : "skip" + } +} +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +You can also associate a single execution mode with all the actions in the watch +using `_all` as the action id: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/my_watch/_execute +{ + "action_modes" : { + "_all" : "force_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] +-------------------------------------------------- +POST _xpack/watcher/watch/_execute +{ + "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" + } + } + } + } +} +-------------------------------------------------- +// CONSOLE + +All other settings for this API still apply when inlining a watch. In the +following snippet, while the inline watch defines a `compare` condition, +during the execution this condition will be ignored: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/watch/_execute +{ + "ignore_condition" : true, + "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" + } + } + } + } +} +-------------------------------------------------- +// CONSOLE diff --git a/docs/public/rest-api/watcher/get-watch.asciidoc b/docs/public/rest-api/watcher/get-watch.asciidoc new file mode 100644 index 00000000000..766b58e28de --- /dev/null +++ b/docs/public/rest-api/watcher/get-watch.asciidoc @@ -0,0 +1,67 @@ +[[watcher-api-get-watch]] +=== Get Watch API + +This API retrieves a watch by its id. + +The following example gets a watch with `my-watch` id: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/watch/my_watch +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +Response: + +[source,js] +-------------------------------------------------- +{ + "found": true, + "_id": "my_watch", + "_status": { <1> + "version": 1, + "state": { + "active": true, + "timestamp": "2015-05-26T18:21:08.630Z" + }, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:21:08.630Z", + "state": "awaits_successful_execution" + } + } + } + }, + "watch": { + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "trigger": { + "schedule": { + "hourly": { + "minute": [0, 5] + } + } + }, + "actions": { + "test_index": { + "index": { + "index": "test", + "doc_type": "test2" + } + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"timestamp": "2015-05-26T18:21:08.630Z"/"timestamp": "$body._status.state.timestamp"/] +<1> The current status of the watch diff --git a/docs/public/rest-api/watcher/put-watch.asciidoc b/docs/public/rest-api/watcher/put-watch.asciidoc new file mode 100644 index 00000000000..c113f233000 --- /dev/null +++ b/docs/public/rest-api/watcher/put-watch.asciidoc @@ -0,0 +1,128 @@ +[[watcher-api-put-watch]] +=== 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). + +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. + If {security} is enabled, make sure no `write` privileges are + granted to anyone over the `.watches` index. + +The following example adds a watch with the `my-watch` id that has the following +characteristics: + +* The watch schedule triggers every minute. +* The watch search input looks for any 404 HTTP responses that occurred in the + last five minutes. +* The watch condition checks if any search hits where found. +* When found, the watch action sends an email to an administrator. + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my-watch +{ + "trigger" : { + "schedule" : { "cron" : "0 0/1 * * * ?" } + }, + "input" : { + "search" : { + "request" : { + "indices" : [ + "logstash*" + ], + "body" : { + "query" : { + "bool" : { + "must" : { + "match": { + "response": 404 + } + }, + "filter" : { + "range": { + "@timestamp": { + "from": "{{ctx.trigger.scheduled_time}}||-5m", + "to": "{{ctx.trigger.triggered_time}}" + } + } + } + } + } + } + } + } + }, + "condition" : { + "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }} + }, + "actions" : { + "email_admin" : { + "email" : { + "to" : "admin@domain.host.com", + "subject" : "404 recently encountered" + } + } + } +} +-------------------------------------------------- +// CONSOLE + +A watch has the following fields: + +[options="header"] +|====== +| Name | Description + +| `trigger` | The <> that defines when the watch + should run. + +| `input` | The <> that defines the input that loads the + data for the watch. + +| `condition` | The <> that defines if the actions + should be run. + +| `actions` | The list of <> 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] +==== Timeouts + +When updating a watch while it is executing, the put action will block and wait +for the watch execution to finish. Depending on the nature of the watch, in some +situations this can take a while. For this reason, the put watch action is +associated with a timeout that is set to 10 seconds by default. You can control +this timeout by passing in the `master_timeout` parameter. + +The following snippet shows how to change the default timeout of the put action +to 30 seconds: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my-watch?master_timeout=30s +-------------------------------------------------- + +[[watcher-api-put-watch-active-state]] +==== Controlling Default Active State + +When adding a watch you can also define its initial <>. +You do that by setting the `active` parameter. The following command add a watch +and sets it to be inactive by default: + +[source,js] +-------------------------------------------------- +PUT _xpack/watcher/watch/my-watch?active=false +-------------------------------------------------- + +NOTE: If you omit the `active` parameter, the watch is active by default. diff --git a/docs/public/rest-api/watcher/restart.asciidoc b/docs/public/rest-api/watcher/restart.asciidoc new file mode 100644 index 00000000000..44aff2d8ca3 --- /dev/null +++ b/docs/public/rest-api/watcher/restart.asciidoc @@ -0,0 +1,21 @@ +[[watcher-api-restart]] +=== Restart API + +The `restart` API stops, then starts the {watcher} service, as in the +following example: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/_restart +-------------------------------------------------- +// CONSOLE + +{watcher} returns the following response if the request is successful: + +[source,js] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/public/rest-api/watcher/start.asciidoc b/docs/public/rest-api/watcher/start.asciidoc new file mode 100644 index 00000000000..ee17c09c71d --- /dev/null +++ b/docs/public/rest-api/watcher/start.asciidoc @@ -0,0 +1,21 @@ +[[watcher-api-start]] +=== Start API + +The `start` API starts the {watcher} service if the service is not already +running, as in the following example: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/_start +-------------------------------------------------- +// CONSOLE + +{watcher} returns the following response if the request is successful: + +[source,js] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/public/rest-api/watcher/stats.asciidoc b/docs/public/rest-api/watcher/stats.asciidoc new file mode 100644 index 00000000000..92100c48299 --- /dev/null +++ b/docs/public/rest-api/watcher/stats.asciidoc @@ -0,0 +1,161 @@ +[[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 supported metrics are: + +[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. +|====== + +The {watcher} `stats` API always returns basic metrics regardless of the +`metric` option. The following example calls the `stats` API including the +basic metrics: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/stats +-------------------------------------------------- +// CONSOLE + +A successful call returns a JSON structure similar to the following example: + +[source,js] +-------------------------------------------------- +{ + "watcher_state": "started", <1> + "watch_count": 1, <2> + "execution_thread_pool": { + "size": 1000, <3> + "max_size": 1 <4> + } +} +-------------------------------------------------- + +<1> The current state of watcher. May be either `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`. + +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: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/stats?metric=executing_watches +-------------------------------------------------- +// CONSOLE + +The following example specifies the `metric` option as part of the url path: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/stats/current_watches +-------------------------------------------------- +// CONSOLE + +The following snippet shows an example of a successful JSON response that +captures a watch in execution: + +[source,js] +-------------------------------------------------- +{ + "watcher_state": "started", + "watch_count": 2, + "execution_thread_pool": { + "queue_size": 1000, + "max_size": 20 + }, + "current_watches": [ <1> + { + "watch_id": "slow_condition", <2> + "watch_record_id": "slow_condition_3-2015-05-13T07:42:32.179Z", <3> + "triggered_time": "2015-05-12T11:53:51.800Z", <4> + "execution_time": "2015-05-13T07:42:32.179Z", <5> + "execution_phase": "condition" <6> + } + ] +} +-------------------------------------------------- + +<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. +<3> The id of the watch record. +<4> The time the watch was triggered by the trigger engine. +<5> The time the watch was executed. This is just before the input is being + executed. +<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: + +[source,js] +-------------------------------------------------- +GET _xpack/watcher/stats/queued_watches +-------------------------------------------------- +// CONSOLE + +An example of a successful JSON response that captures a watch in execution: + +[source,js] +-------------------------------------------------- +{ + "watcher_state": "started", + "watch_count": 10, + "execution_thread_pool": { + "queue_size": 1000, + "max_size": 20 + }, + "queued_watches": [ <1> + { + "watch_id": "slow_condition4", <2> + "watch_record_id": "slow_condition4_223-2015-05-21T11:59:59.811Z", <3> + "triggered_time": "2015-05-21T11:59:59.811Z", <4> + "execution_time": "2015-05-21T11:59:59.811Z" <5> + }, + ... + ] +} +-------------------------------------------------- +<1> A list of all watches that are currently queued for execution. When no + watches are queued, an empty array is returned. +<2> The id of the watch queued for execution. +<3> The id of the watch record. +<4> The time the watch was triggered by the trigger engine. +<5> The time the watch was went into a queued state. diff --git a/docs/public/rest-api/watcher/stop.asciidoc b/docs/public/rest-api/watcher/stop.asciidoc new file mode 100644 index 00000000000..68f61d741c9 --- /dev/null +++ b/docs/public/rest-api/watcher/stop.asciidoc @@ -0,0 +1,21 @@ +[[watcher-api-stop]] +=== Stop API + +The `stop` API stops the {watcher} service if the service is running, as in the +following example: + +[source,js] +-------------------------------------------------- +POST _xpack/watcher/_stop +-------------------------------------------------- +// CONSOLE + +{watcher} returns the following response if the request is successful: + +[source,js] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- +// TESTRESPONSE