[DOCS] Add watcher rest-api docs to x-pack-elasticsearch
Original commit: elastic/x-pack-elasticsearch@a1cb375599
This commit is contained in:
lcawley
parent
979d232faa
commit
8fc5aadec9
|
|
@ -0,0 +1,20 @@
|
|||
[[ml-api]]
|
||||
== Machine Learning APIs
|
||||
|
||||
Use machine learning to detect anomalies in time series data.
|
||||
|
||||
//=== Job Management APIs
|
||||
//* <<ml-put-job>>
|
||||
//* <<ml-delete-job>>
|
||||
//* <<ml-get-job>>
|
||||
//* <<ml-open-close-job>>
|
||||
//* <<ml-flush-job>>
|
||||
//* <<ml-post-data>>
|
||||
|
||||
|
||||
//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[]
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
[[watcher-api]]
|
||||
== Watcher APIs
|
||||
|
||||
* <<watcher-api-put-watch>>
|
||||
* <<watcher-api-get-watch>>
|
||||
* <<watcher-api-delete-watch>>
|
||||
* <<watcher-api-execute-watch>>
|
||||
* <<watcher-api-ack-watch>>
|
||||
* <<watcher-api-activate-watch>>
|
||||
* <<watcher-api-deactivate-watch>>
|
||||
* <<watcher-api-stats>>
|
||||
* <<watcher-api-stop>>
|
||||
* <<watcher-api-start>>
|
||||
* <<watcher-api-restart>>
|
||||
|
||||
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[]
|
||||
|
|
@ -0,0 +1,224 @@
|
|||
[[watcher-api-ack-watch]]
|
||||
=== Ack Watch API
|
||||
|
||||
<<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 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 <<watcher-api-get-watch, Get Watch API>>:
|
||||
|
||||
[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
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
[[watcher-api-activate-watch]]
|
||||
=== Activate Watch API
|
||||
|
||||
A watch can be either <<watch-active-state, active or inactive>>. 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 <<watcher-api-get-watch, Get Watch API>>:
|
||||
|
||||
[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/]
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
[[watcher-api-deactivate-watch]]
|
||||
=== Deactivate Watch API
|
||||
|
||||
A watch can be either <<watch-active-state, active or inactive>>. 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 <<watcher-api-get-watch, Get Watch API>>:
|
||||
|
||||
[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/]
|
||||
|
|
@ -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]
|
||||
|
||||
|
|
@ -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-always, Always>> 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 <<watcher-api-execute-watch-action-mode, Action Execution Modes>>
|
||||
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 <<watch-definition, 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.
|
||||
|======
|
||||
|
||||
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
|
||||
<<actions-email, 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:
|
||||
|
||||
[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
|
||||
|
|
@ -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
|
||||
|
|
@ -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 <<trigger, trigger>> that defines when the watch
|
||||
should run.
|
||||
|
||||
| `input` | The <<input, input>> that defines the input that loads the
|
||||
data for the watch.
|
||||
|
||||
| `condition` | The <<condition, condition>> that defines if the actions
|
||||
should be run.
|
||||
|
||||
| `actions` | The list of <<actions, 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]
|
||||
==== 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 <<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:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/watcher/watch/my-watch?active=false
|
||||
--------------------------------------------------
|
||||
|
||||
NOTE: If you omit the `active` parameter, the watch is active by default.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue