Create or update a watch
Generally available
All methods and paths for this operation:
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.
IMPORTANT: You must use Kibana or this API to create a watch.
Do not add a watch directly to the .watches index by using the Elasticsearch index API.
If Elasticsearch security features are enabled, do not give users write privileges on the .watches index.
When you add a watch you can also define its initial active state by setting the active parameter.
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 runs.
Required authorization
- Cluster privileges:
manage_watcher
Query parameters
-
The initial state of the watch. The default value is
true, which means the watch is active by default. -
only update the watch if the last operation that has changed the watch has the specified primary term
-
only update the watch if the last operation that has changed the watch has the specified sequence number
-
Explicit version number for concurrency control
Body
Required
-
The list of actions that will be run if the condition matches.
-
The condition that defines if the actions should be run.
-
The input that defines the input that loads the data for the watch.
-
Metadata JSON that will be copied into the history entries.
-
The minimum time between actions being run. The default is 5 seconds. This default can be changed in the config file with the setting
xpack.watcher.throttle.period.default_period. If both this value and thethrottle_period_in_millisparameter are specified, Watcher uses the last parameter included in the request. -
Time unit for milliseconds
-
The transform that processes the watch payload to prepare it for the watch actions.
-
The trigger that defines when the watch should run.
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"
}
}
}
}resp = client.watcher.put_watch(
id="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"
}
}
},
)const response = await client.watcher.putWatch({
id: "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",
},
},
},
});response = client.watcher.put_watch(
id: "my-watch",
body: {
"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"
}
}
}
}
)$resp = $client->watcher()->putWatch([
"id" => "my-watch",
"body" => [
"trigger" => [
"schedule" => [
"cron" => "0 0/1 * * * ?",
],
],
"input" => [
"search" => [
"request" => [
"indices" => array(
"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",
],
],
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"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"}}}}' "$ELASTICSEARCH_URL/_watcher/watch/my-watch"client.watcher().putWatch(p -> p
.actions("email_admin", a -> a
.email(e -> e
.subject("404 recently encountered")
.to("admin@domain.host.com")
)
)
.condition(c -> c
.compare(NamedValue.of("ctx.payload.hits.total",Pair.of(ConditionOp.Gt,FieldValue.of(0))))
)
.id("my-watch")
.input(i -> i
.search(s -> s
.request(r -> r
.body(b -> b
.query(q -> q
.bool(bo -> bo
.filter(f -> f
.range(ra -> ra
.untyped(u -> u
.field("@timestamp")
)
)
)
.must(m -> m
.match(ma -> ma
.field("response")
.query(FieldValue.of(404))
)
)
)
)
)
.indices("logstash*")
)
)
)
.trigger(t -> t
.schedule(sc -> sc
.cron("0 0/1 * * * ?")
)
)
);
{
"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"
}
}
}
}