107 lines
3.9 KiB
Plaintext
107 lines
3.9 KiB
Plaintext
[[api-rest-put-watch]]
|
|
==== PUT Watch API
|
|
|
|
The PUT watch API either registers a new watch in watcher or update an existing one. Once registered, a new document
|
|
will be added to the `.watches` index, representing the watch, and the watch's trigger will immediately be registered
|
|
with the relevant trigger engine (typically the scheduler, for the `schedule` trigger).
|
|
|
|
IMPORTANT: Putting a watch must be done via this API only. Do not put a watch directly to the `.watches` index
|
|
using Elasticsearch's Index API. When integrating with Shield, a best practice is to make sure
|
|
no `write` privileges are granted to anyone over the `.watches` API.
|
|
|
|
|
|
The following example adds a watch with the `my-watch` id that has the following qualities:
|
|
|
|
* The watch schedule triggers every minute.
|
|
* The watch search input finds any 404 HTTP responses that occurred in the past five minutes.
|
|
* The watch condition checks the search results for 404s.
|
|
* The watch action sends an email if there are any 404s.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch
|
|
{
|
|
"trigger" : {
|
|
"schedule" : { "cron" : "0 0/1 * * * ?" }
|
|
},
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [
|
|
"logstash*"
|
|
],
|
|
"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"
|
|
},
|
|
"actions" : {
|
|
"email_admin" : {
|
|
"email" : {
|
|
"to" : "admin@domain.host.com",
|
|
"subject" : "404 recently encountered"
|
|
}
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
// AUTOSENSE
|
|
|
|
A watch has the following fields:
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name | Description
|
|
| `trigger` | The <<trigger, trigger>> that defines when the watch should run
|
|
| `input` | The <<input, input>> that defines the input that loads the data for the watch
|
|
| `condition` | The <<condition, condition>> that defines if the actions should be run
|
|
| `actions` | The list of <<actions, actions>> that will be run if the condition matches
|
|
| `meta` | Metadata json that will be copied into the history entries.
|
|
| `throttle_period` | The minimum time between actions being run, the default for this is 5 seconds. This default can be changed in the config file with the setting `watcher.throttle.period.default_period`.
|
|
|======
|
|
|
|
|
|
===== Timeouts
|
|
|
|
When updating a watch while it is executing, the put action will block and wait for the watch execution
|
|
to finish. Depending on the nature of the watch, in some situations this can take a while. For this reason,
|
|
the put watch action is associated with a timeout that is set to 10 seconds by default. You can control this
|
|
timeout by passing in the `master_timeout` parameter.
|
|
|
|
The following snippet shows how to change the default timeout of the put action to 30 seconds:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch?master_timeout=30s
|
|
--------------------------------------------------
|
|
|
|
[[api-rest-put-watch-active-state]]
|
|
===== Controlling Default Active State
|
|
|
|
When adding a watch you can also define its initial <<watch-active-state, active state>>. You do that by
|
|
setting the `active` parameter. The following command add a watch and sets it to be inactive by default:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my-watch?active=false
|
|
--------------------------------------------------
|
|
|
|
NOTE: If you omit the `active` parameter, the watch is set to the active state by default. |