WARNING: Version 6.0 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
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.
PUT _xpack/watcher/watch/<watch_id>/_ack
PUT _xpack/watcher/watch/<watch_id>/_ack/<action_id>
-
action_id - (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.
You must have manage_watcher cluster privileges to use this API. For more
information, see Security Privileges.
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
{
"record_execution" : true
}
GET _xpack/watcher/watch/my_watch
and the action is now in ackable state:
{
"found": true,
"_id": "my_watch",
"status": {
"version": 2,
"actions": {
"test_index": {
"ack": {
"timestamp": "2015-05-26T18:04:27.723Z",
"state": "ackable"
},
"last_execution" : {
"timestamp": "2015-05-25T18:04:27.723Z",
"successful": true
},
"last_successful_execution" : {
"timestamp": "2015-05-25T18:04:27.723Z",
"successful": true
}
}
},
"state": ...,
"last_checked": ...,
"last_met_condition": ...
},
"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": 3,
"actions": {
"test_index": {
"ack": {
"timestamp": "2015-05-26T18:04:27.723Z",
"state": "acked"
},
"last_execution" : {
"timestamp": "2015-05-25T18:04:27.723Z",
"successful": true
},
"last_successful_execution" : {
"timestamp": "2015-05-25T18:04:27.723Z",
"successful": true
}
}
},
"state": ...,
"last_checked": ...,
"last_met_condition": ...
},
"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
The response looks like a get watch response, but only contains the status:
{
"status": {
"state": {
"active": true,
"timestamp": "2015-05-26T18:04:27.723Z"
},
"last_checked": "2015-05-26T18:04:27.753Z",
"last_met_condition": "2015-05-26T18:04:27.763Z",
"actions": {
"test_index": {
"ack" : {
"timestamp": "2015-05-26T18:04:27.713Z",
"state": "acked"
},
"last_execution" : {
"timestamp": "2015-05-25T18:04:27.733Z",
"successful": true
},
"last_successful_execution" : {
"timestamp": "2015-05-25T18:04:27.773Z",
"successful": true
}
}
},
"version": 2
}
}