Ack watch API

Ack watch API

New API reference

For the most up-to-date API details, refer to Watcher APIs.

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. resp = client.watcher.put_watch(
  2.     id="my_watch",
  3.     trigger={
  4.         "schedule": {
  5.             "yearly": {
  6.                 "in": "february",
  7.                 "on": 29,
  8.                 "at": "noon"
  9.             }
  10.         }
  11.     },
  12.     input={
  13.         "simple": {
  14.             "payload": {
  15.                 "send": "yes"
  16.             }
  17.         }
  18.     },
  19.     condition={
  20.         "always": {}
  21.     },
  22.     actions={
  23.         "test_index": {
  24.             "throttle_period": "15m",
  25.             "index": {
  26.                 "index": "test"
  27.             }
  28.         }
  29.     },
  30. )
  31. print(resp)
  1. const response = await client.watcher.putWatch({
  2.   id: "my_watch",
  3.   trigger: {
  4.     schedule: {
  5.       yearly: {
  6.         in: "february",
  7.         on: 29,
  8.         at: "noon",
  9.       },
  10.     },
  11.   },
  12.   input: {
  13.     simple: {
  14.       payload: {
  15.         send: "yes",
  16.       },
  17.     },
  18.   },
  19.   condition: {
  20.     always: {},
  21.   },
  22.   actions: {
  23.     test_index: {
  24.       throttle_period: "15m",
  25.       index: {
  26.         index: "test",
  27.       },
  28.     },
  29.   },
  30. });
  31. console.log(response);
  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. resp = client.watcher.get_watch(
  2.     id="my_watch",
  3. )
  4. print(resp)
  1. const response = await client.watcher.getWatch({
  2.   id: "my_watch",
  3. });
  4. console.log(response);
  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. resp = client.watcher.execute_watch(
  2.     id="my_watch",
  3.     record_execution=True,
  4. )
  5. print(resp)
  7. resp1 = client.watcher.get_watch(
  8.     id="my_watch",
  9. )
  10. print(resp1)
  1. const response = await client.watcher.executeWatch({
  2.   id: "my_watch",
  3.   record_execution: true,
  4. });
  5. console.log(response);
  7. const response1 = await client.watcher.getWatch({
  8.   id: "my_watch",
  9. });
  10. console.log(response1);
  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. resp = client.watcher.ack_watch(
  2.     watch_id="my_watch",
  3.     action_id="test_index",
  4. )
  5. print(resp)
  7. resp1 = client.watcher.get_watch(
  8.     id="my_watch",
  9. )
  10. print(resp1)
  1. const response = await client.watcher.ackWatch({
  2.   watch_id: "my_watch",
  3.   action_id: "test_index",
  4. });
  5. console.log(response);
  7. const response1 = await client.watcher.getWatch({
  8.   id: "my_watch",
  9. });
  10. console.log(response1);
  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. resp = client.watcher.ack_watch(
  2.     watch_id="my_watch",
  3.     action_id="action1,action2",
  4. )
  5. print(resp)
  1. const response = await client.watcher.ackWatch({
  2.   watch_id: "my_watch",
  3.   action_id: "action1,action2",
  4. });
  5. console.log(response);
  1. POST _watcher/watch/my_watch/_ack/action1,action2

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

  1. resp = client.watcher.ack_watch(
  2.     watch_id="my_watch",
  3. )
  4. print(resp)
  1. const response = await client.watcher.ackWatch({
  2.   watch_id: "my_watch",
  3. });
  4. console.log(response);
  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. }