WARNING: Version 5.6 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.
-
master_timeout - (time) A timeout value for the connection to the master node.
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": ...
},
"_status": ...,
"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": ...
},
"_status": ...,
"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": ...
},
"_status": ...,
"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
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