mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-04 09:59:16 +00:00
80593fb23c
The execution state is kind of a global indicator if a watch has been running successfully and is used by the watcher UI. However this field is only stored in the watch history but not part of the watch status, thus it is not available everywhere. In order to simplify the watcher UI this commit also adds the field to the watch status which is stored together with the watch. It is stored under the `status.execution_state` field as `status.state` is already taken. This is also reflects with the name of the java class. The WatchStatus class does not contain serialization checks, as this is intended to be backported to 6.x, where those checks will be added. Once the backport is done, the old execution state field can be fully deleted from the master branch in another commit (syncing with Kibana folks required). relates elastic/x-pack-elasticsearch#2385 * fix doc tests Original commit: elastic/x-pack-elasticsearch@26e8f99571
376 lines
12 KiB
Plaintext
376 lines
12 KiB
Plaintext
[role="xpack"]
|
|
[[watcher-api-execute-watch]]
|
|
=== Execute Watch API
|
|
|
|
The execute watch API forces the execution of a stored watch. It can be used to
|
|
force execution of the watch outside of its triggering logic, or to simulate the
|
|
watch execution for debugging purposes.
|
|
|
|
[float]
|
|
==== Request
|
|
|
|
`POST _xpack/watcher/watch/<watch_id>/_execute` +
|
|
|
|
`POST _xpack/watcher/watch/_execute`
|
|
|
|
[float]
|
|
==== Description
|
|
|
|
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.
|
|
|
|
[float]
|
|
[[watcher-api-execute-inline-watch]]
|
|
===== Inline Watch Execution
|
|
|
|
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}.
|
|
|
|
[float]
|
|
==== Path Parameters
|
|
|
|
`watch_id`::
|
|
(string) Identifier for the watch.
|
|
|
|
[float]
|
|
==== Query Parameters
|
|
|
|
`debug`::
|
|
(boolean) Defines whether the watch runs in debug mode. The default value is
|
|
`false`.
|
|
|
|
[float]
|
|
==== Request Body
|
|
|
|
This API supports the following fields:
|
|
|
|
[cols=",^,^,", options="header"]
|
|
|======
|
|
| 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
|
|
{xpack-ref}/condition-always.html[Always Condition].
|
|
This can also be specified as a 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 <<watcher-api-execute-watch-action-mode, 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 a HTTP parameter.
|
|
|
|
| `watch` | no | null | When present, this
|
|
{xpack-ref}/how-watcher-works.html#watch-definition[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.
|
|
|======
|
|
|
|
[float]
|
|
[[watcher-api-execute-watch-action-mode]]
|
|
===== Action Execution Modes
|
|
|
|
Action modes define how actions are handled during the watch execution. There
|
|
are five possible modes an action can be associated with:
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name | Description
|
|
|
|
| `simulate` | The action execution is simulated. Each action type
|
|
define its own simulation operation mode. For example, the
|
|
{xpack-ref}/actions-email.html[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 the `simulate` mode, except the action is
|
|
not be 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 would have 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.
|
|
|======
|
|
|
|
[float]
|
|
==== Authorization
|
|
You must have `manage_watcher` cluster privileges to use this API. For more
|
|
information, see {xpack-ref}/security-privileges.html[Security Privileges].
|
|
|
|
[float]
|
|
==== Examples
|
|
|
|
The following example executes the `my_watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
The following example shows a comprehensive example of executing the `my-watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"trigger_data" : { <1>
|
|
"triggered_time" : "now",
|
|
"scheduled_time" : "now"
|
|
},
|
|
"alternative_input" : { <2>
|
|
"foo" : "bar"
|
|
},
|
|
"ignore_condition" : true, <3>
|
|
"action_modes" : {
|
|
"my-action" : "force_simulate" <4>
|
|
},
|
|
"record_execution" : true <5>
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
<1> The triggered and schedule times are provided.
|
|
<2> The input as defined by the watch is ignored and instead the provided input
|
|
is used as the execution payload.
|
|
<3> The condition as defined by the watch is ignored and is assumed to
|
|
evaluate to `true`.
|
|
<4> 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.
|
|
<5> 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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_id": "my_watch_0-2015-06-02T23:17:55.124Z", <1>
|
|
"watch_record": { <2>
|
|
"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": { <3>
|
|
"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",
|
|
"type": "test2",
|
|
"version": 1,
|
|
"created": true,
|
|
"result": "created",
|
|
"id": "AVSHKzPa9zx62AzUzFXY"
|
|
}
|
|
},
|
|
"status": "success",
|
|
"type": "index"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/my_watch_0-2015-06-02T23:17:55.124Z/$body._id/]
|
|
// TESTRESPONSE[s/"triggered_time": "2015-06-02T23:17:55.124Z"/"triggered_time": "$body.watch_record.trigger_event.triggered_time"/]
|
|
// TESTRESPONSE[s/"scheduled_time": "2015-06-02T23:17:55.124Z"/"scheduled_time": "$body.watch_record.trigger_event.manual.schedule.scheduled_time"/]
|
|
// TESTRESPONSE[s/"execution_time": "2015-06-02T23:17:55.124Z"/"execution_time": "$body.watch_record.result.execution_time"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.111Z"/"timestamp": "$body.watch_record.status.state.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.124Z"/"timestamp": "$body.watch_record.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"last_checked": "2015-06-02T23:17:55.124Z"/"last_checked": "$body.watch_record.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": "2015-06-02T23:17:55.124Z"/"last_met_condition": "$body.watch_record.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"execution_duration": 12608/"execution_duration": "$body.watch_record.result.execution_duration"/]
|
|
// TESTRESPONSE[s/"id": "AVSHKzPa9zx62AzUzFXY"/"id": "$body.watch_record.result.actions.0.index.response.id"/]
|
|
// TESTRESPONSE[s/"node": "my_node"/"node": "$body.watch_record.node"/]
|
|
<1> The id of the watch record as it would be stored in the `.watcher-history` index.
|
|
<2> The watch record document as it would be stored in the `.watcher-history` index.
|
|
<3> The watch execution results.
|
|
|
|
You can set a different execution mode for every action by associating the mode
|
|
name with the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"action1" : "force_simulate",
|
|
"action2" : "skip"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
You can also associate a single execution mode with all the actions in the watch
|
|
using `_all` as the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"_all" : "force_execute"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
The following example shows how to execute a watch inline:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|