22[[watcher-ui]]
33== Watcher
44
5- Watcher is an {es} feature that you can use to create actions based on
6- conditions, which are periodically evaluated using queries on your data.
7- Watches are helpful for analyzing mission-critical and business-critical
8- streaming data. For example, you might watch application logs for performance
5+ Watcher is an {es} feature that you can use to create actions based on
6+ conditions, which are periodically evaluated using queries on your data.
7+ Watches are helpful for analyzing mission-critical and business-critical
8+ streaming data. For example, you might watch application logs for performance
99outages or audit access logs for security threats.
1010
11- To get started with the Watcher UI, go to *Management > Elasticsearch > Watcher*.
11+ To get started with the Watcher UI, go to *Management > Elasticsearch > Watcher*.
1212With this UI, you can:
1313
1414* <<watcher-create-threshold-alert, Create a simple threshold watch>>
@@ -20,10 +20,10 @@ With this UI, you can:
2020image:management/watcher-ui/images/watches.png["Watcher list"]
2121
2222{ref}/xpack-alerting.html[Alerting on cluster and index events]
23- is a good source for detailed
24- information on how watches work. If you are using the UI to create a
25- threshold watch, take a look at the different watcher actions. If you are
26- creating an advanced watch, you should be familiar with the parts of a
23+ is a good source for detailed
24+ information on how watches work. If you are using the UI to create a
25+ threshold watch, take a look at the different watcher actions. If you are
26+ creating an advanced watch, you should be familiar with the parts of a
2727watch—input, schedule, condition, and actions.
2828
2929[float]
@@ -40,41 +40,40 @@ and either of these watcher roles:
4040* `watcher_admin`. You can perform all Watcher actions, including create and edit watches.
4141* `watcher_user`. You can view watches, but not create or edit them.
4242
43- You can manage roles in *Management > Security > Roles*, or use the
44- <<role-management-api, Kibana Role Management API>>. Watches are shared between
45- all users with the same role.
43+ You can manage roles in *Management > Security > Roles*, or use the
44+ <<role-management-api, Kibana Role Management API>>. Watches are shared between
45+ all users with the same role.
4646
47- NOTE: If you are creating a threshold watch, you must also have index management
48- privileges. See
47+ NOTE: If you are creating a threshold watch, you must also have the `view_index_metadata` index privilege. See
4948<<managing-indices, Managing Indices>> for detailed information.
5049
5150[float]
5251[[watcher-create-threshold-alert]]
5352=== Create a threshold alert
5453
55- A threshold alert is one of the most common types of watches that you can create.
56- This alert periodically checks when your data is above, below, equals,
54+ A threshold alert is one of the most common types of watches that you can create.
55+ This alert periodically checks when your data is above, below, equals,
5756or is in between a certain threshold within a given time interval.
5857
59- The following example walks you through creating a threshold alert. The alert
60- is triggered when the maximum total CPU usage on a machine goes above a
61- certain percentage. The example uses https://www.elastic.co/products/beats/metricbeat[Metricbeat]
62- to collect metrics from your systems and services.
63- {metricbeat-ref}/metricbeat-installation.html[Learn more] on how to install
58+ The following example walks you through creating a threshold alert. The alert
59+ is triggered when the maximum total CPU usage on a machine goes above a
60+ certain percentage. The example uses https://www.elastic.co/products/beats/metricbeat[Metricbeat]
61+ to collect metrics from your systems and services.
62+ {metricbeat-ref}/metricbeat-installation.html[Learn more] on how to install
6463and get started with Metricbeat.
6564
6665[float]
6766==== Define the watch input and schedule
6867
69- . Click *Create* and then select *Create threshold alert*.
68+ . Click *Create* and then select *Create threshold alert*.
7069+
7170You're navigated to a page where you're asked to define the watch name, the data that you want to evaluate, and
7271how often you want to trigger the watch.
7372
7473. Enter a name that you want to call the alert, for example, `cpu_threshold_alert`.
7574
76- . In the *Indices to query* field, enter `metricbeat-*` and select `@timestamp`
77- as the time field.
75+ . In the *Indices to query* field, enter `metricbeat-*` and select `@timestamp`
76+ as the time field.
7877
7978. Use the default schedule to run the watch every 1 minute.
8079+
@@ -84,22 +83,22 @@ image:management/watcher-ui/images/threshold-alert/create-threshold-alert-create
8483[float]
8584==== Add a condition
8685
87- You should now see a panel with default conditions and a visualization of the
88- data based on those conditions. The condition evaluates the data you’ve loaded
86+ You should now see a panel with default conditions and a visualization of the
87+ data based on those conditions. The condition evaluates the data you’ve loaded
8988into the watch and determines if any action is required.
9089
91- . Click the `WHEN` expression and change the value to `max()`.
90+ . Click the `WHEN` expression and change the value to `max()`.
9291+
93- The `OF` expression now appears.
92+ The `OF` expression now appears.
9493
95- . Search for `system.process.cpu.total.norm.pct` and select it from the list.
94+ . Search for `system.process.cpu.total.norm.pct` and select it from the list.
9695
9796
98- . Select the `IS ABOVE` expression and change the value to `.25` to trigger
97+ . Select the `IS ABOVE` expression and change the value to `.25` to trigger
9998an alert whenever the CPU is above 25%.
10099+
101- As you change the condition, the visualization is automatically updated. The black
102- line represents the threshold (25%), while the green fluctuating line
100+ As you change the condition, the visualization is automatically updated. The black
101+ line represents the threshold (25%), while the green fluctuating line
103102represents the change in CPU over the set time period.
104103+
105104[role="screenshot"]
@@ -108,46 +107,46 @@ image:management/watcher-ui/images/threshold-alert/threshold-alert-condition.png
108107[float]
109108==== Add an action
110109
111- Now that the condition is set, you must add an action. The action triggers
112- when the watch condition is met. For a complete list of actions and how to configure them, see
110+ Now that the condition is set, you must add an action. The action triggers
111+ when the watch condition is met. For a complete list of actions and how to configure them, see
113112{ref}/action-conditions.html[Adding conditions to actions].
114113
115114In this example, you’ll configure an email action. You must have an {ref}/actions-email.html#configuring-email[email account configured]
116- in {es} for this example to work.
115+ in {es} for this example to work.
117116
118117. Click *Add action* and select *Email*.
119118
120- . In the *To email address* field, enter one or more email addresses to whom
121- you want to send the message when the condition is met.
119+ . In the *To email address* field, enter one or more email addresses to whom
120+ you want to send the message when the condition is met.
122121
123122. Enter a subject and body for the email.
124123+
125124[role="screenshot"]
126125image:management/watcher-ui/images/threshold-alert/threshold-alert-action.png["Action for threshold alert"]
127126
128- . To test the action before saving the watch, click *Send test email*.
127+ . To test the action before saving the watch, click *Send test email*.
129128+
130129A sample email is sent using the configuration you set up.
131130
132- . Click *Create alert*.
131+ . Click *Create alert*.
133132+
134- The alert appears on the Watcher overview page, where you can drill down into
133+ The alert appears on the Watcher overview page, where you can drill down into
135134the watch history and status.
136135
137136[float]
138137==== Delete the alert
139138
140- In this example, you set the threshold to 25% so you can see the watch fire. In
141- a real-world scenario, this threshold is likely too low because the alerts are
142- so frequent. Once you are done experimenting, you should delete the alert.
139+ In this example, you set the threshold to 25% so you can see the watch fire. In
140+ a real-world scenario, this threshold is likely too low because the alerts are
141+ so frequent. Once you are done experimenting, you should delete the alert.
143142Find the alert on the Watcher overview page and click the trash icon in the *Actions* column.
144143
145144[float]
146145==== Edit the alert
147146
148- Alternatively, you can keep the alert and adjust the threshold value. To edit
149- an alert, find the alert on the Watcher overview page and click the pencil icon
150- in the *Actions* column.
147+ Alternatively, you can keep the alert and adjust the threshold value. To edit
148+ an alert, find the alert on the Watcher overview page and click the pencil icon
149+ in the *Actions* column.
151150
152151[float]
153152[[watcher-getting-started]]
@@ -161,24 +160,24 @@ last fired, and last triggered. A watch has one of four states:
161160* *Disabled.* The watch will not fire under any circumstances.
162161
163162From this page you can drill down into a watch to investigate its history
164- and status.
163+ and status.
165164
166165[float]
167166==== View watch history
168167
169- The *Execution history* tab shows each time the watch is triggered and the
170- results of the query, whether the condition was met, and what actions were taken.
168+ The *Execution history* tab shows each time the watch is triggered and the
169+ results of the query, whether the condition was met, and what actions were taken.
171170
172171[role="screenshot"]
173172image:management/watcher-ui/images/execution-history.png["Execution history tab"]
174173
175174[float]
176175==== Acknowledge action status
177176
178- The *Action statuses* tab lists all actions associated with the watch and
179- the state of each action. If the action is firing, you can acknowledge the
180- watch to prevent too many executions of the same action for the same watch.
181- See {ref}/actions.html#actions-ack-throttle[Acknowledgement and throttling] for details.
177+ The *Action statuses* tab lists all actions associated with the watch and
178+ the state of each action. If the action is firing, you can acknowledge the
179+ watch to prevent too many executions of the same action for the same watch.
180+ See {ref}/actions.html#actions-ack-throttle[Acknowledgement and throttling] for details.
182181
183182[role="screenshot"]
184183image:management/watcher-ui/images/alerts-status.png["Action status tab"]
@@ -189,44 +188,44 @@ image:management/watcher-ui/images/alerts-status.png["Action status tab"]
189188
190189Actions for deactivating and deleting a watch are on each watch detail page:
191190
192- * *Deactivate a watch* if you know a situation is planned that will
193- cause a false alarm. You can reactivate the watch when the situation is resolved.
194- * *Delete a watch* to permanently remove it from the system. You can delete
195- the watch you are currently viewing, or go to the Watcher overview, and
196- delete watches in bulk.
191+ * *Deactivate a watch* if you know a situation is planned that will
192+ cause a false alarm. You can reactivate the watch when the situation is resolved.
193+ * *Delete a watch* to permanently remove it from the system. You can delete
194+ the watch you are currently viewing, or go to the Watcher overview, and
195+ delete watches in bulk.
197196
198197[float]
199198[[watcher-create-advanced-watch]]
200199=== Create an advanced watch
201200
202- Advanced watches are for users who are more familiar with {es} query syntax and
203- the Watcher framework. The UI is aligned with using the REST APIs.
201+ Advanced watches are for users who are more familiar with {es} query syntax and
202+ the Watcher framework. The UI is aligned with using the REST APIs.
204203For more information, see {ref}/query-dsl.html[Query DSL].
205204
206205[float]
207206==== Create the watch
208207
209- On the Watch overview page, click *Create* and choose *Create advanced watch*.
210- An advanced watch requires a name and ID. Name is a user-friendly way to
211- identify the watch, and ID refers to the identifier used by {es}. Refer to
212- {ref}/how-watcher-works.html#watch-definition[Watch definition] for how
213- to input the watch JSON.
208+ On the Watch overview page, click *Create* and choose *Create advanced watch*.
209+ An advanced watch requires a name and ID. Name is a user-friendly way to
210+ identify the watch, and ID refers to the identifier used by {es}. Refer to
211+ {ref}/how-watcher-works.html#watch-definition[Watch definition] for how
212+ to input the watch JSON.
214213
215214[role="screenshot"]
216215image:management/watcher-ui/images/advanced-watch/advanced-watch-create.png["Create advanced watch"]
217216
218217[float]
219218==== Simulate the watch
220219
221- The *Simulate* tab allows you to override parts of the watch, and then run a
220+ The *Simulate* tab allows you to override parts of the watch, and then run a
222221simulation. Be aware of these implementation details on overrides:
223222
224223* Trigger overrides use {ref}/common-options.html#date-math[date math].
225224* Input overrides accepts a JSON blob.
226225* Condition overrides indicates if you want to force the condition to always be `true`.
227226* Action overrides support {ref}/watcher-api-execute-watch.html#watcher-api-execute-watch-action-mode[multiple options].
228227
229- After starting the simulation, you’ll see a results screen. For more information
228+ After starting the simulation, you’ll see a results screen. For more information
230229on the fields in the response, see the {ref}/watcher-api-execute-watch.html[Execute watch API].
231230
232231[role="screenshot"]
@@ -235,7 +234,7 @@ image:management/watcher-ui/images/advanced-watch/advanced-watch-simulate.png["C
235234[float]
236235==== Examples of advanced watches
237236
238- Refer to these examples for creating an advanced watch:
237+ Refer to these examples for creating an advanced watch:
239238
240239* {ref}/watch-cluster-status.html[Watch the status of an {es} cluster]
241240* {ref}/watching-meetup-data.html[Watch event data]
0 commit comments