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.

› › ›

Execute watch API

edit

Execute watch API

edit

Forces the execution of a stored watch.

Request

edit

POST _watcher/watch/<watch_id>/_execute

POST _watcher/watch/_execute

Prerequisites

edit

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

Description

edit

This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.

Inline watch execution

edit

You can use the Execute API to execute watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

Path parameters

edit

<watch_id>: (Optional, string) Identifier for the watch.

Query parameters

edit

debug: (Optional, Boolean) Defines whether the watch runs in debug mode. The default value is false.

Request body

edit

This API supports the following fields:

Name	Required	Default	Description
`trigger_data`	no		This structure is parsed as the data of the trigger event that will be used during the watch execution
`ignore_condition`	no	false	When set to `true`, the watch execution uses the always condition. This can also be specified as an HTTP parameter.
`alternative_input`	no	null	When present, the watch uses this object as a payload instead of executing its own input.
`action_modes`	no	null	Determines how to handle the watch actions as part of the watch execution. See Action execution modes for more information.
`record_execution`	no	false	When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter.
`watch`	no	null	When present, this watch is used instead of the one specified in the request. This watch is not persisted to the index and record_execution cannot be set.

Action execution modes

edit

Action modes define how actions are handled during the watch execution. There are five possible modes an action can be associated with:

Name	Description
`simulate`	The action execution is simulated. Each action type defines its own simulation operation mode. For example, the `email` action creates the email that would have been sent but does not actually send it. In this mode, the action might be throttled if the current state of the watch indicates it should be.
`force_simulate`	Similar to the `simulate` mode, except the action is not throttled even if the current state of the watch indicates it should be.
`execute`	Executes the action as it would have been executed if the watch had been triggered by its own trigger. The execution might be throttled if the current state of the watch indicates it should be.
`force_execute`	Similar to the `execute` mode, except the action is not throttled even if the current state of the watch indicates it should be.
`skip`	The action is skipped and is not executed or simulated. Effectively forces the action to be throttled.

Security integration

edit

When Elasticsearch security features are enabled on your cluster, watches are executed with the privileges of the user that stored the watches. If your user is allowed to read index a, but not index b, then the exact same set of rules will apply during execution of a watch.

When using the execute watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.

Examples

edit

The following example executes the my_watch watch:

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

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

POST _watcher/watch/my_watch/_execute

The following example shows a comprehensive example of executing the my-watch watch:

resp = client.watcher.execute_watch(
    id="my_watch",
    trigger_data={
        "triggered_time": "now",
        "scheduled_time": "now"
    },
    alternative_input={
        "foo": "bar"
    },
    ignore_condition=True,
    action_modes={
        "my-action": "force_simulate"
    },
    record_execution=True,
)
print(resp)

const response = await client.watcher.executeWatch({
  id: "my_watch",
  trigger_data: {
    triggered_time: "now",
    scheduled_time: "now",
  },
  alternative_input: {
    foo: "bar",
  },
  ignore_condition: true,
  action_modes: {
    "my-action": "force_simulate",
  },
  record_execution: true,
});
console.log(response);

POST _watcher/watch/my_watch/_execute
{
  "trigger_data" : { 
     "triggered_time" : "now",
     "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}

	The triggered and schedule times are provided.
	The input as defined by the watch is ignored and instead the provided input is used as the execution payload.
	The condition as defined by the watch is ignored and is assumed to evaluate to `true`.
	Forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being executed normally.
	The execution of the watch creates a watch record in the watch history, and the throttling state of the watch is potentially updated accordingly.

This is an example of the output:

{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "@timestamp": "2015-06-02T23:17:55.124Z",
    "watch_id": "my_watch",
    "node": "my_node",
    "messages": [],
    "trigger_event": {
      "type": "manual",
      "triggered_time": "2015-06-02T23:17:55.124Z",
      "manual": {
        "schedule": {
          "scheduled_time": "2015-06-02T23:17:55.124Z"
        }
      }
    },
    "state": "executed",
    "status": {
      "version": 1,
      "execution_state": "executed",
      "state": {
        "active": true,
        "timestamp": "2015-06-02T23:17:55.111Z"
      },
      "last_checked": "2015-06-02T23:17:55.124Z",
      "last_met_condition": "2015-06-02T23:17:55.124Z",
      "actions": {
        "test_index": {
          "ack": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "state": "ackable"
          },
          "last_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          },
          "last_successful_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          }
        }
      }
    },
    "input": {
      "simple": {
        "payload": {
          "send": "yes"
        }
      }
    },
    "condition": {
      "always": {}
    },
    "result": { 
      "execution_time": "2015-06-02T23:17:55.124Z",
      "execution_duration": 12608,
      "input": {
        "type": "simple",
        "payload": {
          "foo": "bar"
        },
        "status": "success"
      },
      "condition": {
        "type": "always",
        "met": true,
        "status": "success"
      },
      "actions": [
        {
          "id": "test_index",
          "index": {
            "response": {
              "index": "test",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    },
    "user": "test_admin" 
  }
}

	The id of the watch record as it would be stored in the `.watcher-history` index.
	The watch record document as it would be stored in the `.watcher-history` index.
	The watch execution results.
	The user used to execute the watch.

You can set a different execution mode for every action by associating the mode name with the action id:

resp = client.watcher.execute_watch(
    id="my_watch",
    action_modes={
        "action1": "force_simulate",
        "action2": "skip"
    },
)
print(resp)

const response = await client.watcher.executeWatch({
  id: "my_watch",
  action_modes: {
    action1: "force_simulate",
    action2: "skip",
  },
});
console.log(response);

POST _watcher/watch/my_watch/_execute
{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}

You can also associate a single execution mode with all the actions in the watch using _all as the action id:

resp = client.watcher.execute_watch(
    id="my_watch",
    action_modes={
        "_all": "force_execute"
    },
)
print(resp)

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

POST _watcher/watch/my_watch/_execute
{
  "action_modes" : {
    "_all" : "force_execute"
  }
}

The following example shows how to execute a watch inline:

resp = client.watcher.execute_watch(
    watch={
        "trigger": {
            "schedule": {
                "interval": "10s"
            }
        },
        "input": {
            "search": {
                "request": {
                    "indices": [
                        "logs"
                    ],
                    "body": {
                        "query": {
                            "match": {
                                "message": "error"
                            }
                        }
                    }
                }
            }
        },
        "condition": {
            "compare": {
                "ctx.payload.hits.total": {
                    "gt": 0
                }
            }
        },
        "actions": {
            "log_error": {
                "logging": {
                    "text": "Found {{ctx.payload.hits.total}} errors in the logs"
                }
            }
        }
    },
)
print(resp)

const response = await client.watcher.executeWatch({
  watch: {
    trigger: {
      schedule: {
        interval: "10s",
      },
    },
    input: {
      search: {
        request: {
          indices: ["logs"],
          body: {
            query: {
              match: {
                message: "error",
              },
            },
          },
        },
      },
    },
    condition: {
      compare: {
        "ctx.payload.hits.total": {
          gt: 0,
        },
      },
    },
    actions: {
      log_error: {
        logging: {
          text: "Found {{ctx.payload.hits.total}} errors in the logs",
        },
      },
    },
  },
});
console.log(response);

POST _watcher/watch/_execute
{
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}

All other settings for this API still apply when inlining a watch. In the following snippet, while the inline watch defines a compare condition, during the execution this condition will be ignored:

resp = client.watcher.execute_watch(
    ignore_condition=True,
    watch={
        "trigger": {
            "schedule": {
                "interval": "10s"
            }
        },
        "input": {
            "search": {
                "request": {
                    "indices": [
                        "logs"
                    ],
                    "body": {
                        "query": {
                            "match": {
                                "message": "error"
                            }
                        }
                    }
                }
            }
        },
        "condition": {
            "compare": {
                "ctx.payload.hits.total": {
                    "gt": 0
                }
            }
        },
        "actions": {
            "log_error": {
                "logging": {
                    "text": "Found {{ctx.payload.hits.total}} errors in the logs"
                }
            }
        }
    },
)
print(resp)

const response = await client.watcher.executeWatch({
  ignore_condition: true,
  watch: {
    trigger: {
      schedule: {
        interval: "10s",
      },
    },
    input: {
      search: {
        request: {
          indices: ["logs"],
          body: {
            query: {
              match: {
                message: "error",
              },
            },
          },
        },
      },
    },
    condition: {
      compare: {
        "ctx.payload.hits.total": {
          gt: 0,
        },
      },
    },
    actions: {
      log_error: {
        logging: {
          text: "Found {{ctx.payload.hits.total}} errors in the logs",
        },
      },
    },
  },
});
console.log(response);

POST _watcher/watch/_execute
{
  "ignore_condition" : true,
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}

« Delete watch API Get watch API »