Ack watch API

Acknowledging a watch enables you to manually throttle execution of the watch’s actions.

Request

PUT _watcher/watch/<watch_id>/_ack

PUT _watcher/watch/<watch_id>/_ack/<action_id>

Prerequisites

  • You must have manage_watcher cluster privileges to use this API. For more information, see Security privileges.

Description

An action’s acknowledgement state is stored in the status.actions.<id>.ack.state structure.

If the specified watch is currently being executed, this API will return an error. The reason for this is to prevent overwriting of the watch status from a watch execution.

Path parameters

<action_id>

(Optional, 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.

Examples

To demonstrate let’s create a new watch:

  1. PUT _watcher/watch/my_watch
  2. {
  3.   "trigger" : {
  4.     "schedule" : {
  5.       "yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
  6.     }
  7.   },
  8.   "input": {
  9.     "simple": {
  10.       "payload": {
  11.         "send": "yes"
  12.       }
  13.     }
  14.   },
  15.   "condition": {
  16.     "always": {}
  17.   },
  18.   "actions": {
  19.     "test_index": {
  20.       "throttle_period": "15m",
  21.       "index": {
  22.         "index": "test"
  23.       }
  24.     }
  25.   }
  26. }

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:

  1. GET _watcher/watch/my_watch

The action state of a newly-created watch is awaits_successful_execution:

  1. {
  2.   "found": true,
  3.   "_seq_no": 0,
  4.   "_primary_term": 1,
  5.   "_version": 1,
  6.   "_id": "my_watch",
  7.   "status": {
  8.     "version": 1,
  9.     "actions": {
  10.       "test_index": {
  11.         "ack": {
  12.           "timestamp": "2015-05-26T18:04:27.723Z",
  13.           "state": "awaits_successful_execution"
  14.         }
  15.       }
  16.     },
  17.     "state": ...
  18.   },
  19.   "watch": ...
  20. }

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:

  1. POST _watcher/watch/my_watch/_execute
  2. {
  3.   "record_execution" : true
  4. }
  6. GET _watcher/watch/my_watch

and the action is now in ackable state:

  1. {
  2.   "found": true,
  3.   "_id": "my_watch",
  4.   "_seq_no": 1,
  5.   "_primary_term": 1,
  6.   "_version": 2,
  7.   "status": {
  8.     "version": 2,
  9.     "actions": {
  10.       "test_index": {
  11.         "ack": {
  12.           "timestamp": "2015-05-26T18:04:27.723Z",
  13.           "state": "ackable"
  14.         },
  15.         "last_execution" : {
  16.           "timestamp": "2015-05-25T18:04:27.723Z",
  17.           "successful": true
  18.         },
  19.         "last_successful_execution" : {
  20.           "timestamp": "2015-05-25T18:04:27.723Z",
  21.           "successful": true
  22.         }
  23.       }
  24.     },
  25.     "state": ...,
  26.     "execution_state": "executed",
  27.     "last_checked": ...,
  28.     "last_met_condition": ...
  29.   },
  30.   "watch": ...
  31. }

Now we can acknowledge it:

  1. PUT _watcher/watch/my_watch/_ack/test_index
  2. GET _watcher/watch/my_watch
  1. {
  2.   "found": true,
  3.   "_id": "my_watch",
  4.   "_seq_no": 2,
  5.   "_primary_term": 1,
  6.   "_version": 3,
  7.   "status": {
  8.     "version": 3,
  9.     "actions": {
  10.       "test_index": {
  11.         "ack": {
  12.           "timestamp": "2015-05-26T18:04:27.723Z",
  13.           "state": "acked"
  14.         },
  15.         "last_execution" : {
  16.           "timestamp": "2015-05-25T18:04:27.723Z",
  17.           "successful": true
  18.         },
  19.         "last_successful_execution" : {
  20.           "timestamp": "2015-05-25T18:04:27.723Z",
  21.           "successful": true
  22.         }
  23.       }
  24.     },
  25.     "state": ...,
  26.     "execution_state": "executed",
  27.     "last_checked": ...,
  28.     "last_met_condition": ...
  29.   },
  30.   "watch": ...
  31. }

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:

  1. POST _watcher/watch/my_watch/_ack/action1,action2

To acknowledge all of the actions of a watch, simply omit the actions parameter:

  1. POST _watcher/watch/my_watch/_ack

The response looks like a get watch response, but only contains the status:

  1. {
  2.   "status": {
  3.     "state": {
  4.       "active": true,
  5.       "timestamp": "2015-05-26T18:04:27.723Z"
  6.     },
  7.     "last_checked": "2015-05-26T18:04:27.753Z",
  8.     "last_met_condition": "2015-05-26T18:04:27.763Z",
  9.     "actions": {
  10.       "test_index": {
  11.         "ack" : {
  12.           "timestamp": "2015-05-26T18:04:27.713Z",
  13.           "state": "acked"
  14.         },
  15.         "last_execution" : {
  16.           "timestamp": "2015-05-25T18:04:27.733Z",
  17.           "successful": true
  18.         },
  19.         "last_successful_execution" : {
  20.           "timestamp": "2015-05-25T18:04:27.773Z",
  21.           "successful": true
  22.         }
  23.       }
  24.     },
  25.     "execution_state": "executed",
  26.     "version": 2
  27.   }
  28. }