mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-27 23:49:13 +00:00
Today, once you add a watch to watcher, it's always active. Being "active" means that the watch is registered with the trigger engine (scheduled) and will be executed when its trigger is triggered. Quite often, ppl want to have an option to deactivate/disable a registered watch. Such that while the watch definition still exists in watcher, it is "inactive" and is never triggered. The only way to do this today is using a "hack" where you can change the watch schedule to a cron expression targeting a really far date in the future (say somewhere around 2050). Again.. this is very hackish and it requires changing the actual definition of the watch (you loose its original trigger). This commit introduces the notion of an active/inactive watch.. here are the differences between the two states: - active: the watch is registered with watcher and with the trigger engine and will be executed when its trigger is fired by the engine - inactive: the watch is registered with watcher, but is not registered with the trigger engine. An inactive watch will never be fired, regardless of its trigger. This commit also adds two new APIs: - `_watcher/watch/{id}/_activate` - `_watcher/watch/{id}/_deactivate` to activate and deactivate existing watches. In addition, the Put Watch API now accepts an `active` parameter that indicates the initial state of the put watch (by default set to `true`, i.e. "active"). Closes elastic/elasticsearch#90 Original commit: elastic/x-pack-elasticsearch@37b9ab4d54
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. |