This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

› › ›

Ack watch API

edit

Ack watch API

edit

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

Request

edit

PUT _watcher/watch/<watch_id>/_ack

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

Prerequisites

edit

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

Description

edit

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

edit

<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

edit

To demonstrate let’s create a new watch:

resp = client.watcher.put_watch(
    id="my_watch",
    trigger={
        "schedule": {
            "yearly": {
                "in": "february",
                "on": 29,
                "at": "noon"
            }
        }
    },
    input={
        "simple": {
            "payload": {
                "send": "yes"
            }
        }
    },
    condition={
        "always": {}
    },
    actions={
        "test_index": {
            "throttle_period": "15m",
            "index": {
                "index": "test"
            }
        }
    },
)
print(resp)

const response = await client.watcher.putWatch({
  id: "my_watch",
  trigger: {
    schedule: {
      yearly: {
        in: "february",
        on: 29,
        at: "noon",
      },
    },
  },
  input: {
    simple: {
      payload: {
        send: "yes",
      },
    },
  },
  condition: {
    always: {},
  },
  actions: {
    test_index: {
      throttle_period: "15m",
      index: {
        index: "test",
      },
    },
  },
});
console.log(response);

PUT _watcher/watch/my_watch
{
  "trigger" : {
    "schedule" : {
      "yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
    }
  },
  "input": {
    "simple": {
      "payload": {
        "send": "yes"
      }
    }
  },
  "condition": {
    "always": {}
  },
  "actions": {
    "test_index": {
      "throttle_period": "15m",
      "index": {
        "index": "test"
      }
    }
  }
}

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:

resp = client.watcher.get_watch(
    id="my_watch",
)
print(resp)

const response = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response);

GET _watcher/watch/my_watch

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

{
  "found": true,
  "_seq_no": 0,
  "_primary_term": 1,
  "_version": 1,
  "_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:

resp = client.watcher.execute_watch(
    id="my_watch",
    record_execution=True,
)
print(resp)

resp1 = client.watcher.get_watch(
    id="my_watch",
)
print(resp1)

const response = await client.watcher.executeWatch({
  id: "my_watch",
  record_execution: true,
});
console.log(response);

const response1 = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response1);

POST _watcher/watch/my_watch/_execute
{
  "record_execution" : true
}

GET _watcher/watch/my_watch

and the action is now in ackable state:

{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 1,
  "_primary_term": 1,
  "_version": 2,
  "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": ...,
    "execution_state": "executed",
    "last_checked": ...,
    "last_met_condition": ...
  },
  "watch": ...
}

Now we can acknowledge it:

resp = client.watcher.ack_watch(
    watch_id="my_watch",
    action_id="test_index",
)
print(resp)

resp1 = client.watcher.get_watch(
    id="my_watch",
)
print(resp1)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
  action_id: "test_index",
});
console.log(response);

const response1 = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response1);

PUT _watcher/watch/my_watch/_ack/test_index
GET _watcher/watch/my_watch

{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 2,
  "_primary_term": 1,
  "_version": 3,
  "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": ...,
    "execution_state": "executed",
    "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:

resp = client.watcher.ack_watch(
    watch_id="my_watch",
    action_id="action1,action2",
)
print(resp)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
  action_id: "action1,action2",
});
console.log(response);

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

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

resp = client.watcher.ack_watch(
    watch_id="my_watch",
)
print(resp)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
});
console.log(response);

POST _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
        }
      }
    },
    "execution_state": "executed",
    "version": 2
  }
}

« Watcher APIs Activate watch API »