WARNING: Version 5.1 of the Elastic Stack 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.
Ack Watch API
editAck Watch API
editAcknowledging 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
editIf 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
editThe 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]"
}
}
}
}
}