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:
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"
}
}
}
}The current status of a watch and the state of its actions is returned with the watch definition when you call the Get Watch API:
GET _xpack/watcher/watch/my_watch
The action state of a newly-created watch is awaits_successful_execution:
{
"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": ...
}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:
POST _xpack/watcher/watch/my_watch/_execute GET _xpack/watcher/watch/my_watch
and the action is now in ackable state:
{
"found": true,
"_id": "my_watch",
"_status": {
"version": 1,
"actions": {
"test_index": {
"ack": {
"timestamp": "2015-05-26T18:04:27.723Z",
"state": "ackable"
}
}
},
"state": ...
},
"watch": ...
}Now we can acknowledge it:
PUT _xpack/watcher/watch/my_watch/_ack/test_index GET _xpack/watcher/watch/my_watch
{
"found": true,
"_id": "my_watch",
"_status": {
"version": 1,
"actions": {
"test_index": {
"ack": {
"timestamp": "2015-05-26T18:04:27.723Z",
"state": "acknowledged"
}
}
},
"state": ...
},
"watch": ...
}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:
POST _xpack/watcher/watch/my_watch/_ack/action1,action2
To acknowledge all of the actions of a watch, simply omit the actions
parameter:
POST _xpack/watcher/watch/my_watch/_ack
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:
POST _xpack/watcher/watch/my_watch/_ack?master_timeout=30s
Response format
The response format looks like:
{
"_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]"
}
}
}
}
}