317 lines
11 KiB
Plaintext
317 lines
11 KiB
Plaintext
[[api-rest-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 test the watch for
|
|
debugging purposes.
|
|
|
|
The following example executes the `my-watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my-watch/_execute
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
For testing and debugging purposes, you also have fine-grained control on how the
|
|
watch is executed--execute the watch without executing all of its actions or by simply
|
|
simulating them. You can also force execution by ignoring the watch's condition and
|
|
control whether a watch record would be written to the watch history after execution.
|
|
|
|
This API supports the following fields:
|
|
|
|
[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 <<condition-always, Always>>
|
|
Condition.
|
|
|
|
| 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
|
|
<<api-rest-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 `.watch_history` index for the current time.
|
|
In addition, the status of the watch is
|
|
updated, possbily throttling subsequent executions.
|
|
|
|
| watch | no | null | When present, this <<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.
|
|
|======
|
|
|
|
The following example shows a comprehensive example of executing the `my-watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _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>
|
|
}
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
<1> The triggered and schedule times are provided.
|
|
<2> The input as defined by the watch is ignored and instead the
|
|
provided input will be used as the execution payload.
|
|
<3> The condition as defined by the watch will be ignored and will
|
|
be 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 will create a watch record in the
|
|
watch history, and the throttling state of the watch will
|
|
potentially be 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",
|
|
"trigger_event": {
|
|
"type": "manual",
|
|
"triggered_time": "2015-06-02T23:17:55.124Z",
|
|
"manual": {
|
|
"schedule": {
|
|
"scheduled_time": "2015-06-02T23:17:55.124Z"
|
|
}
|
|
}
|
|
},
|
|
"state": "executed",
|
|
"input": {
|
|
"search": {
|
|
"request": {
|
|
"search_type": "query_then_fetch",
|
|
"indices": [
|
|
"logstash*"
|
|
],
|
|
"types": [],
|
|
"body": {
|
|
"query": {
|
|
"filtered": {
|
|
"query": {
|
|
"match": {
|
|
"response": 404
|
|
}
|
|
},
|
|
"filter": {
|
|
"range": {
|
|
"@timestamp": {
|
|
"from": "{{ctx.trigger.scheduled_time}}||-5m",
|
|
"to": "{{ctx.trigger.triggered_time}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition": {
|
|
"script": "ctx.payload.hits.total > 1"
|
|
},
|
|
"result": { <3>
|
|
"execution_time": "2015-06-02T23:17:55.124Z",
|
|
"execution_duration": 12608,
|
|
"input": {
|
|
"type": "simple",
|
|
"payload": {
|
|
"foo": "bar"
|
|
}
|
|
},
|
|
"condition": {
|
|
"type": "always",
|
|
"met": true
|
|
},
|
|
"actions": [
|
|
{
|
|
"id": "email_admin",
|
|
"type" : "email"
|
|
"status" : "success"
|
|
"email": {
|
|
"account": "gmail",
|
|
"email": {
|
|
"id": "my-watch_0-2015-05-30T01:14:05.319Z",
|
|
"from": "watcher@example.com",
|
|
"sent_date": "2015-05-30T01:14:05.319Z",
|
|
"to": [
|
|
"admin@domain.host.com"
|
|
],
|
|
"subject": "404 recently encountered"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> The id of the watch record as it would be stored in the `.watch_history` index.
|
|
<2> The watch record document as it would be stored in the `.watch_history` index.
|
|
<3> The watch execution results.
|
|
|
|
[[api-rest-execute-watch-action-mode]]
|
|
===== Action Execution Modes
|
|
|
|
Action modes define how actions will be handled during the watch execution. There are five
|
|
possible modes an action can be associated with:
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name |Description
|
|
|
|
| simulate | The action execution will be simulated. Each action type define its own
|
|
simulation mode. For example, The <<actions-email, email>> action
|
|
will create the email that would have been sent but will not actually
|
|
send it. In this mode, the action may be throttled if the current state
|
|
of the watch indicates it should be.
|
|
|
|
| force_simulate | Similar to the the `simulate` mode, except the action will 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 may be throttled if the
|
|
current state of the watch indicates it should be.
|
|
|
|
| force_execute | Similar to the `execute` mode, except the action ill not be throttled
|
|
even if the current state of the watch indicates it should be.
|
|
|
|
| skip | The action will be skipped and won't be executed or simulated.
|
|
Effectively forcing the action to be throttled.
|
|
|======
|
|
|
|
You can set a different execution mode for every action by simply associating the mode name
|
|
with the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my-watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"action1" : "force_simulate",
|
|
"action2" : "skip"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
You can also associate a single execution mode with all the watch's actions using `_all`
|
|
as the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my-watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"_all" : "force_execute"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
[[api-rest-execute-inline-watch]]
|
|
===== Inline Watch Execution
|
|
|
|
You can use the Execute API to execute watches that are not yet registered in Watcher by
|
|
specifying the watch definition inline. This serves as great tool for testing and debugging
|
|
your watches prior to adding them to Watcher.
|
|
|
|
The following example demonstrates how you can test a watch defintion:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
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 take effect when inlining a watch.
|
|
In the following snippet, while the watch is defined with a `compare` condition,
|
|
during execution this condition will be ignored:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|