mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
91 lines
4.2 KiB
Text
91 lines
4.2 KiB
Text
[discrete]
|
|
[[api-java-put-watch]]
|
|
=== Create or update watch API
|
|
|
|
The create or update 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 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 add a watch
|
|
directly to the `.watches` index using Elasticsearch's Index API.
|
|
When the {es} {security-features} are enabled, make sure no `write`
|
|
privileges are granted to anyone over the `.watches` index.
|
|
|
|
|
|
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 hits where found.
|
|
* When hits are found, the watch action sends an email to the administrator.
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
WatchSourceBuilder watchSourceBuilder = WatchSourceBuilders.watchBuilder();
|
|
|
|
// Set the trigger
|
|
watchSourceBuilder.trigger(TriggerBuilders.schedule(Schedules.cron("0 0/1 * * * ?")));
|
|
|
|
// Create the search request to use for the input
|
|
SearchRequest request = Requests.searchRequest("idx").source(searchSource()
|
|
.query(boolQuery()
|
|
.must(matchQuery("response", 404))
|
|
.filter(rangeQuery("date").gt("{{ctx.trigger.scheduled_time}}"))
|
|
.filter(rangeQuery("date").lt("{{ctx.execution_time}}"))
|
|
));
|
|
|
|
// Create the search input
|
|
SearchInput input = new SearchInput(new WatcherSearchTemplateRequest(new String[]{"idx"}, null, SearchType.DEFAULT,
|
|
WatcherSearchTemplateRequest.DEFAULT_INDICES_OPTIONS, new BytesArray(request.source().toString())), null, null, null);
|
|
|
|
// Set the input
|
|
watchSourceBuilder.input(input);
|
|
|
|
// Set the condition
|
|
watchSourceBuilder.condition(new ScriptCondition(new Script("ctx.payload.hits.total > 1")));
|
|
|
|
// Create the email template to use for the action
|
|
EmailTemplate.Builder emailBuilder = EmailTemplate.builder();
|
|
emailBuilder.to("someone@domain.host.com");
|
|
emailBuilder.subject("404 recently encountered");
|
|
EmailAction.Builder emailActionBuilder = EmailAction.builder(emailBuilder.build());
|
|
|
|
// Add the action
|
|
watchSourceBuilder.addAction("email_someone", emailActionBuilder);
|
|
|
|
PutWatchResponse putWatchResponse = watcherClient.preparePutWatch("my-watch")
|
|
.setSource(watchSourceBuilder)
|
|
.get();
|
|
--------------------------------------------------
|
|
|
|
While the above snippet flashes out all the concrete classes that make our watch,
|
|
using the available builder classes along with static imports can significantly
|
|
simplify and compact your code:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
PutWatchResponse putWatchResponse2 = watcherClient.preparePutWatch("my-watch")
|
|
.setSource(watchBuilder()
|
|
.trigger(schedule(cron("0 0/1 * * * ?")))
|
|
.input(searchInput(new WatcherSearchTemplateRequest(new String[]{"idx"}, null, SearchType.DEFAULT,
|
|
WatcherSearchTemplateRequest.DEFAULT_INDICES_OPTIONS, searchSource()
|
|
.query(boolQuery()
|
|
.must(matchQuery("response", 404))
|
|
.filter(rangeQuery("date").gt("{{ctx.trigger.scheduled_time}}"))
|
|
.filter(rangeQuery("date").lt("{{ctx.execution_time}}"))
|
|
).buildAsBytes())))
|
|
.condition(compareCondition("ctx.payload.hits.total", CompareCondition.Op.GT, 1L))
|
|
.addAction("email_someone", emailAction(EmailTemplate.builder()
|
|
.to("someone@domain.host.com")
|
|
.subject("404 recently encountered"))))
|
|
.get();
|
|
--------------------------------------------------
|
|
|
|
* Use `TriggerBuilders` and `Schedules` classes to define the trigger
|
|
* Use `InputBuilders` class to define the input
|
|
* Use `ConditionBuilders` class to define the condition
|
|
* Use `ActionBuilders` to define the actions
|