[[introduction]]
== 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.

[float]
== Alerting and Notification

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.

[float]
== Watcher Concepts

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.

[float]
== Where to Go Next

<<customizing-watches,Customizing Watches>> :: Learn more about how watches are configured and how
											                         you create custom watches.
<<example-watches, Example Watches>> 		    :: See complete example watches for common scenarios.
<<reference, 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. 

[float]
== Have Comments, Questions, or Feedback?

Head over to our {forum}[Watcher Discussion Forum] to share you experience, questions, and
suggestions.