149 lines
4.4 KiB
Plaintext
149 lines
4.4 KiB
Plaintext
[[api-rest-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.
|
|
|
|
The current status of a watch and the state of its actions is returned with the watch
|
|
definition when you call the <<api-rest-get-watch, Get Watch API>>:
|
|
|
|
[source,json]
|
|
--------------------------------------------------
|
|
GET _watcher/watch/<watch_id>
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
The action state of a newly-created watch is `awaits_successful_execution`.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"_status": {
|
|
...
|
|
"actions": {
|
|
"action_id": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "awaits_successful_execution"
|
|
},
|
|
...
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
When the watch runs and the condition matches, the value of the `ack.state` changes
|
|
to `ackable`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"_status": {
|
|
...
|
|
"actions": {
|
|
"action_id": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:19:08.758Z",
|
|
"state": "ackable"
|
|
},
|
|
...
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Acknowledging the watch action (using the ACK API) sets the value of the `ack.state`
|
|
to `acked`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"_status": {
|
|
...
|
|
"actions": {
|
|
"action_id": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:21:09.982Z",
|
|
"state": "acked"
|
|
},
|
|
...
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Acknowledging an action throttles further executions of that action until its
|
|
`ack.state` is reset to `awaits_successful_execution`. This happens when the watch's condition
|
|
is checked and is not met (the condition evaluates to `false`).
|
|
|
|
The following snippet shows how to ack a watch action identified by its id. In this example, the
|
|
watch id is `my-watch` and the id of the action being acknowledged is `my-action`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch/my-action/_ack
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
As a response to this request, the full watch status is returned:
|
|
|
|
[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]"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
You can acknowledge multiple actions by assigning the `actions` parameter a
|
|
comma-separated list of action ids:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch/action1,action2/_ack
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
To acknowledge all of a watch's actions, simply omit the `actions` parameter:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch/_ack
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
===== Timeouts
|
|
|
|
If you acknowledge a watch while it is executing, the ack action blocks and waits for the watch
|
|
execution to finish. For some watches, this can take a significant amount of time. By default,
|
|
the ack watch 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 ack action to 30 seconds:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch/_ack?master_timeout=30s
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|