233 lines
6.9 KiB
Plaintext
233 lines
6.9 KiB
Plaintext
[[watcher-getting-started]]
|
|
== Getting Started with {watcher}
|
|
|
|
{Watcher} is automatically enabled when you <<installing-xpack, install
|
|
{xpack}>> into Elasticsearch and Kibana.
|
|
|
|
[[watch-log-data]]
|
|
To set up a watch to start sending alerts:
|
|
|
|
* <<log-add-input, Schedule the watch and define an input>>.
|
|
* <<log-add-condition, Add a condition>> that checks to see if an alert
|
|
needs to be sent.
|
|
* <<log-take-action, Configure an action>> to send an alert when the
|
|
condition is met.
|
|
|
|
[float]
|
|
[[log-add-input]]
|
|
=== Schedule the Watch and Define an Input
|
|
|
|
A watch <<trigger-schedule, schedule>> controls how often a watch is triggered.
|
|
The watch <<input, input>> gets the data that you want to evaluate.
|
|
|
|
To periodically search log data and load the results into the
|
|
watch, you could use an <<schedule-interval, interval>> schedule and a
|
|
<<input-search, search>> input. For example, the following Watch searches
|
|
the `logs` index for errors every 10 seconds:
|
|
|
|
[source,js]
|
|
------------------------------------------------------------
|
|
PUT _xpack/watcher/watch/log_error_watch
|
|
{
|
|
"trigger" : {
|
|
"schedule" : { "interval" : "10s" } <1>
|
|
},
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : {
|
|
"match" : { "message": "error" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
<1> Schedules are typically configured to run less frequently. This example sets
|
|
the interval to 10 seconds so you can easily see the watches being triggered.
|
|
Since this watch runs so frequently, don't forget to <<log-delete, delete the watch>>
|
|
when you're done experimenting.
|
|
|
|
If you check the watch history you'll see that the watch is being triggered every
|
|
10 seconds. However, the search isn't returning any results so nothing is loaded
|
|
into the watch payload.
|
|
|
|
For example, the following request retrieves the last ten watch executions (watch
|
|
records) from the watch history:
|
|
|
|
[source,js]
|
|
------------------------------------------------------------
|
|
GET .watcher-history*/_search?pretty
|
|
{
|
|
"sort" : [
|
|
{ "result.execution_time" : "desc" }
|
|
]
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
[float]
|
|
[[log-add-condition]]
|
|
=== Add a Condition
|
|
|
|
A <<condition, condition>> evaluates the data you've loaded into the watch and
|
|
determines if any action is required. Now that you've loaded log errors into
|
|
the watch, you can define a condition that checks to see if any errors were
|
|
found.
|
|
|
|
For example, the following compare condition simply checks to see if the
|
|
search input returned any hits.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _xpack/watcher/watch/log_error_watch
|
|
{
|
|
"trigger" : { "schedule" : { "interval" : "10s" }},
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : {
|
|
"match" : { "message": "error" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition" : {
|
|
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }} <1>
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
<1> The <<condition-compare, compare>> condition lets you easily compare against
|
|
values in the execution context.
|
|
|
|
For this compare condition to evaluate to `true`, you need to add an event
|
|
to the `logs` index that contains an error. For example, the following request
|
|
adds a 404 error to the `logs` index:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST logs/event
|
|
{
|
|
"timestamp" : "2015-05-17T18:12:07.613Z",
|
|
"request" : "GET index.html",
|
|
"status_code" : 404,
|
|
"message" : "Error: File not found"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
Once you add this event, the next time the watch executes its condition will
|
|
evaluate to `true`. The condition result is recorded as part of the
|
|
`watch_record` each time the watch executes, so you can verify whether or
|
|
not the condition was met by searching the watch history:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET .watcher-history*/_search?pretty
|
|
{
|
|
"query" : {
|
|
"bool" : {
|
|
"must" : [
|
|
{ "match" : { "result.condition.met" : true }},
|
|
{ "range" : { "result.execution_time" : { "from" : "now-10s" }}}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
[float]
|
|
[[log-take-action]]
|
|
=== Configure an Action
|
|
|
|
Recording watch records in the watch history is nice, but the real power of
|
|
{watcher} is being able to do something when the watch condition is met. A
|
|
watch's <<actions, actions>> define what to do when the watch condition
|
|
evaluates to `true`. You can send emails, call third-party webhooks, write
|
|
documents to an Elasticsearch index, or log messages to the standard
|
|
Elasticsearch log files.
|
|
|
|
For example, the following action writes a message to the Elasticsearch
|
|
log when an error is detected.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT _xpack/watcher/watch/log_error_watch
|
|
{
|
|
"trigger" : { "schedule" : { "interval" : "10s" }},
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : {
|
|
"match" : { "message": "error" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition" : {
|
|
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
|
|
},
|
|
"actions" : {
|
|
"log_error" : {
|
|
"logging" : {
|
|
"text" : "Found {{ctx.payload.hits.total}} errors in the logs"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[float]
|
|
[[log-delete]]
|
|
=== Delete the Watch
|
|
|
|
Since the `log_error_watch` is configured to run every 10 seconds, make sure you
|
|
delete it when you're done experimenting. Otherwise, the noise from this sample
|
|
watch will make it hard to see what else is going on in your watch history and
|
|
log file.
|
|
|
|
To remove the watch, use the <<watcher-api-delete-watch, DELETE watch>> API:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE _xpack/watcher/watch/log_error_watch
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
[float]
|
|
[[required-security-privileges]]
|
|
=== Required Security Privileges
|
|
To use Watcher, users must have the following security privileges:
|
|
|
|
* Cluster `manage` privilege. Enables users to access the Watcher APIs.
|
|
* Index `read` privilege on `.watch*` indices. Enables users to read the `.watches` and .`watcher-history-*` indices.
|
|
|
|
[float]
|
|
[[next-steps]]
|
|
=== Where to Go Next
|
|
|
|
* See <<how-watcher-works, How {watcher} Works>> for more information about the
|
|
anatomy of a watch and the watch lifecycle.
|
|
* See <<example-watches, Example Watches>> for more examples of setting up
|
|
a watch.
|
|
* See the https://github.com/elastic/examples/tree/master/Alerting[Example
|
|
Watches] in the Elastic Examples repo for additional sample watches you can use
|
|
as a starting point for building custom watches.
|