WARNING: Version 5.5 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
The PUT watch API either registers a new watch in Watcher or update an existing one.
PUT _xpack/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.
Putting a watch must be done via this API only. Do not put a watch
directly to the .watches index using the Elasticsearch Index API.
If X-Pack security is enabled, make sure no write privileges are
granted to anyone over 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) - (string) Identifier for the watch.
-
active -
(boolean) Defines whether the watch is active or inactive by default. The
default value is
true, which means the watch is active by default. -
master_timeout - (time) A timeout value for the connection to the master node.
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.
The following example adds a watch with the my-watch id that has the following
characteristics:
- The watch schedule triggers every minute.
- The watch search input looks for any 404 HTTP responses that occurred in the last five minutes.
- The watch condition checks if any search hits where found.
- When found, the watch action sends an email to an administrator.
PUT _xpack/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" : "[email protected]",
"subject" : "404 recently encountered"
}
}
}
}
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:
PUT _xpack/watcher/watch/my-watch?master_timeout=30s
When adding 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 _xpack/watcher/watch/my-watch?active=false
If you omit the active parameter, the watch is active by default.