The PUT watch API either registers a new watch in Watcher or updates an existing one.
PUT _watcher/watch/<watch_id>
When a watch is registered, a new document that represents the watch is added to
the .watches
index and its trigger is immediately registered with the relevant
trigger engine. Typically for the schedule
trigger, the scheduler is the
trigger engine.
You must use Kibana or this API to create a watch. Do not put a watch
directly to the .watches
index using the Elasticsearch index API.
If Elasticsearch security features are enabled, do not give users write
privileges on the .watches
index.
When adding a watch you can also define its initial
active state. You do that
by setting the active
parameter.
watch_id
(required)
active
true
, which means the watch is active by default.
A watch has the following fields:
Name | Description |
---|---|
| The trigger that defines when the watch should run. |
| The input that defines the input that loads the data for the watch. |
| The condition that defines if the actions should be run. |
| The list of actions that will be run if the condition matches |
| Metadata json that will be copied into the history entries. |
| 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 |
You must have manage_watcher
cluster privileges to use this API. For more
information, see Security Privileges.
When Elasticsearch security features are enabled, your watch can index or search only
on indices for which the user that stored the watch has privileges. If the user
is able to read index a
, but not index b
, the same will apply, when the watch
is executed.
The following example adds a watch with the my-watch
id that has the following
characteristics:
PUT _watcher/watch/my-watch { "trigger" : { "schedule" : { "cron" : "0 0/1 * * * ?" } }, "input" : { "search" : { "request" : { "indices" : [ "logstash*" ], "body" : { "query" : { "bool" : { "must" : { "match": { "response": 404 } }, "filter" : { "range": { "@timestamp": { "from": "{{ctx.trigger.scheduled_time}}||-5m", "to": "{{ctx.trigger.triggered_time}}" } } } } } } } } }, "condition" : { "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }} }, "actions" : { "email_admin" : { "email" : { "to" : "admin@domain.host.com", "subject" : "404 recently encountered" } } } }
When you add a watch you can also define its initial
active state. You do that
by setting the active
parameter. The following command adds a watch and sets
it to be inactive by default:
PUT _watcher/watch/my-watch?active=false
If you omit the active
parameter, the watch is active by default.