Introduction

Watcher is a plugin for Elasticsearch that provides alerting and notification based on changes in your data. This guide describes how to install, manage, and use Watcher.

Alerting and Notification

edit

With simple REST APIs, Elasticsearch is a platform that encourages integration and automation for a wide range of use-cases. Increasingly, these use-cases require taking action based on changes or anomalies in the data. For example, you might want to:

Monitor social media as another way to detect failures in user-facing automated systems like ATMs or ticketing systems. When the number of tweets and posts in an area exceeds a threshold of significance, notify a service technician.
Monitor your infrastructure, tracking disk usage over time. Open a helpdesk ticket when any servers are likely to run out of free space in the next few days.
Track network activity to detect malicious activity, and proactively change firewall configuration to reject the malicious user.
Monitor Elasticsearch, and send immediate notification to the system administrator if nodes leave the cluster or query throughput exceeds an expected range.
Track application response times and if page-load time exceeds SLAs for more than 5 minutes, open a helpdesk ticket. If SLAs are exceeded for an hour, page the administrator on duty.

All of these use-cases share a few key properties:

The relevant data or changes in data can be identified with a periodic Elasticsearch query.
The results of the query can be checked against a condition.
One or more actions are taken if the condition is true — an email is sent, a 3rd party system is notified, or the query results are stored.

Watcher Concepts

edit

Watcher provides an API for creating, managing and testing watches. A watch describes a single alert in Watcher, which can contain multiple notification actions.

At a high-level, a typical watch is built from four simple building blocks:

schedule: Define the schedule on which to trigger the query and check the condition.
Query: Specify the query to run as input to the condition. Watcher supports the full Elasticsearch query language, including aggregations.
Condition: Define your condition to determine whether to execute the actions. You can use simple conditions (always true), or use scripting for more sophisticated scenarios.
Actions: Define one or more actions, such as sending email, pushing data to 3rd party systems via webhook, or indexing the results of your query.

A full history of all watches is maintained in an Elasticsearch index. This history keeps track of each time a watch is triggered and records the results from the query, whether the condition was met, and what actions were taken.

Where to Go Next

edit

Customizing Watches: Learn more about how watches are configured and how you create custom watches.
Example Watches: See complete example watches for common scenarios.
Reference:: Full documentation of the watch constructs and the Watcher REST and Java APIs.

We designed Watcher to address a wide range of alerting, and notification needs. We hope you like it.

Have Comments, Questions, or Feedback?

edit

Head over to our Watcher Discussion Forum to share you experience, questions, and suggestions.

Getting Started »