[DOCS] Updates Watcher docs to match updated UI (#40106)

* [DOCS] Updates Watcher docs to match updated UI

* [DOCS] Incoporates watcher review comments and adds badge

* [DOCS] Updated watcher security doc based on feedback

* Update docs/management/watcher-ui/index.asciidoc

Co-Authored-By: Lisa Cawley <lcawley@elastic.co>

docs/management/watcher-ui/create-advanced-watch.asciidoc

@@ -1,54 +1,46 @@
+[role="xpack"]
 [[watcher-create-advanced-watch]]
-=== Create Advanced Watch
+=== Create an advanced watch
 
-Advanced watches are for people who are more familiar with Elasticsearch query syntax and the watcher framework overall. The creation UI is more closely aligned with using the REST apis directly. For 
-more information, see {ref}/query-dsl.html[Query DSL].
+Advanced watches are for users who are more familiar with {es} query syntax and 
+the Watcher framework. The UI is aligned with using the REST APIs. 
+For more information, see {ref}/query-dsl.html[Query DSL].
 
-To create an advanced watch:
-
-* Click the *Create advanced watch* button.
-
-==== Advanced Watch UI
-
-This screen lets you define the core properties of an advanced watch.
-
-[role="screenshot"]
-image:management/watcher-ui/images/advanced-watch/advanced-watch-create.png["Create Advanced Watch",link="management/watcher-ui/images/advanced-watch/advanced-watch-create.png"]
-
-The `ID` refers to the identifier used by Elasticsearch, whereas `Name` is the more user-friendly way to identify the watch. Refer to the 
-{stack-ov}/how-watcher-works.html#watch-definition[Watch definition documentation] 
-for the Watch JSON.
 
 [float]
-=== Simulate
+==== Create the watch
+
+On the Watch overview page, click *Create* and choose *Create advanced watch*.  
+An advanced watch requires a name and ID.  `Name` is a user-friendly way to 
+identify the watch, and `ID` refers to the identifier used by {es}.  Refer to 
+{stack-ov}/how-watcher-works.html#watch-definition[Watch definition] for how 
+to input the watch JSON.  
 
 [role="screenshot"]
-image:management/watcher-ui/images/advanced-watch/advanced-watch-simulate.png["Simulate Advanced Watch",link="management/watcher-ui/images/advanced-watch/advanced-watch-simulate.png"]
+image:management/watcher-ui/images/advanced-watch/advanced-watch-create.png["Create advanced watch"]
 
-This screen allows you to override parts of the watch and then run a simulation of it.
+[float]
+==== Simulate the watch
 
-Some implementation details on overrides:
+The *Simulate* tab allows you to override parts of the watch, and then run a 
+simulation. Be aware of these implementation details on overrides:
 
 * Trigger overrides use {ref}/common-options.html#date-math[date math].
-* Input override accepts a JSON blob that overrides the `input`.
-* Condition overrides is just a checkbox to indicate if you want to force the condition to always be true.
-* Action overrides support multiple options, which are {ref}/watcher-api-execute-watch.html#watcher-api-execute-watch-action-mode[explained here].
+* Input overrides accepts a JSON blob.
+* Condition overrides indicates if you want to force the condition to always be `true`.
+* Action overrides support {ref}/watcher-api-execute-watch.html#watcher-api-execute-watch-action-mode[multiple options].
 
-[float]
-=== Simulated
-
-After starting the simulation, the UI will show a results screen.
+After starting the simulation, you’ll see a results screen. For more information 
+on the fields in the response, see the {ref}//watcher-api-execute-watch.html[Execute Watch API].
 
 [role="screenshot"]
-image:management/watcher-ui/images/advanced-watch/advanced-watch-simulated.png["Simulated Advanced Watch",link="management/watcher-ui/images/advanced-watch/advanced-watch-simulated.png"]
+image:management/watcher-ui/images/advanced-watch/advanced-watch-simulate.png["Create advanced watch"]
 
-The possible simulation statuses for watches are:
+[float]
+==== Example watches
 
-* `Firing` - The watch is currently triggered and is actively performing the associated actions.
-* `Error` - The watch is an error state and not properly working.
-* `Ok` - The watch is not actively firing but working properly.
-* `Disabled` - The watch will not fire under any circumstance.
+Refer to these examples for creating an advanced watch: 
 
-For more information on the various fields in the response, see the 
-{ref}/watcher-api-execute-watch.html[Execute Watch API].
+* {stack-ov}/watch-cluster-status.html[Watch the status of an {es} cluster]
+* {stack-ov}/watching-meetup-data.html[Watch event data]
 

docs/management/watcher-ui/create-threshold-alert.asciidoc

@@ -1,73 +1,107 @@
+[role="xpack"]
 [[watcher-create-threshold-alert]]
-=== Create Threshold Alert
+=== Create a threshold alert
 
-You can create a threshold alert to periodically check when your data goes above or below a certain threshold within a given time interval. It's one of the most common type of alerts that you can create using Watcher. For more advanced watches, see the <<watcher-create-advanced-watch>>.
+A threshold alert is one of the most common types of watches that you can create.  
+This alert periodically checks when your data is above, below, equals, 
+or is in between a certain threshold within a given time interval.
 
-To create a threshold alert:
+The following example walks you through creating a threshold alert. The alert 
+is triggered when the maximum total CPU usage on a machine goes above a 
+certain percentage. The example uses https://www.elastic.co/products/beats/metricbeat[Metricbeat] 
+to collect metrics from your systems and services. 
+{metricbeat-ref}/metricbeat-installation.html[Learn more] on how to install 
+and get started with Metricbeat.
 
-* Click the *Create threshold alert* button.
+[float]
+==== Get started
 
-==== Inputs & Triggers
+. Go to *Management > Elasticsearch > Watcher*.
 
-You must first configure the inputs and triggers.
+. Click *Create* and then select *Create threshold alert*. 
 
-. Add a `name` for the alert.
-. Choose one or more indices that have a time-based field as the alert input.
-. Configure a trigger interval.
+
+[float]
+==== Define the watch input and schedule
+
+You're navigated to a page that walks you through creating the alert.
+You're asked to define the watch name, the data that you want to evaluate, and
+how often you want to trigger the watch. 
+
+. Enter a name that you want to call the alert, for example, `cpu_threshold_alert`.
+
+. In the *Indices to query* field, enter `metricbeat-*` and select `@timestamp` 
+as the time field. 
+
+. Use the default schedule to run the watch every 1 minute.
 +
 [role="screenshot"]
-image:management/watcher-ui/images/threshold-alert/create-threshold-alert-created.png["Created Threshold Alert",link="management/watcher-ui/images/threshold-alert/create-threshold-alert-created.png"]
+image:management/watcher-ui/images/threshold-alert/create-threshold-alert-created.png["Input and schedule for threshold alert"]
 
-==== Condition
+[float]
+==== Add a condition
 
-Here, you can configure the condition that will cause alert to trigger. The UI is interactive and selecting the various elements within the expression will display a UI to change the values.
+You should now see a panel with default conditions and a visualization of the 
+data based on those conditions. The condition evaluates the data you’ve loaded 
+into the watch and determines if any action is required.
 
+. Click the `WHEN` expression and change the value to `max()`. 
++
+The `OF` expression now appears.  
+
+. Search for `system.process.cpu.total.norm.pct` and select it from the list. 
+
+
+. Select the `IS ABOVE` expression and change the value to `.25` to trigger 
+an alert whenever the CPU is above 25%.
++
+As you change the condition, the visualization is automatically updated. The black 
+line represents the threshold (25%), while the green fluctuating line 
+represents the change in CPU over the set time period.
++
 [role="screenshot"]
-image:management/watcher-ui/images/threshold-alert/threshold-alert-aggType.png["Threshold Alert Agg Type",link="management/watcher-ui/images/threshold-alert/threshold-alert-aggType.png"]
+image:management/watcher-ui/images/threshold-alert/threshold-alert-condition.png["Condition for threshold alert"]
 
-Here are a few examples of common alerts based on x-pack monitoring data:
+[float]
+==== Add an action
 
-* High heap usage:
-image:management/watcher-ui/images/threshold-alert/high-heap-usage.png["Threshold Alert Example High Heap Usage",link="management/watcher-ui/images/threshold-alert/high-heap-usage.png"]
+Now that the condition is set, you must add an action. The action triggers 
+when the watch condition is met. For a complete list of actions and how to configure them, see 
+{stack-ov}/action-conditions.html[Adding conditions to actions].
 
-* System load:
-image:management/watcher-ui/images/threshold-alert/system-load.png["Threshold Alert Example System Load",link="management/watcher-ui/images/threshold-alert/system-load.png"]
+In this example, you’ll configure an email action. You must have an {stack-ov}/actions-email.html#configuring-email[email account configured]
+in {es} for this example to work. 
 
+. Click *Add action* and select *Email*.
 
-Here are some specifics of how the visualization works:
+. In the *To email address* field, enter one or more email addresses to whom 
+you want to send the message when the condition is met. 
 
-* The time window that is used in the visualization is calculated by taking the duration defined in the expression and multiplying it by 5. So, if you select `FOR THE LAST 5 hours`, the visualization will show data from the last 25 hours.
+. Enter a subject and body for the email.
++
+[role="screenshot"]
+image:management/watcher-ui/images/threshold-alert/threshold-alert-action.png["Action for threshold alert"]
 
-* In the chart, you will see a blue line that represents the aggregated data. There is also a red line that represents the threshold value.
+. To test the action before saving the watch, click *Send test email*. 
++
+A sample email is sent using the configuration you set up.
 
-* If you use the `terms` aggregation to aggregate over a specific field, there will be multiple visualizations available and pagination controls will appear as shown below.
+. Click *Create alert*.  
++
+The alert appears on the Watcher overview page, where you can drill down into 
+the watch history and status.
 
-** image:management/watcher-ui/images/threshold-alert/threshold-alert-groupBy-pagination.png["Threshold Alert Group By pagination",link="management/watcher-ui/images/threshold-alert/threshold-alert-groupBy-pagination.png"]
+[float]
+==== Delete the alert
 
-==== Actions
-
-Here you can configure the various actions that will occur when the alert fires.
-
-Click `Add new action` to trigger a dropdown selection:
-
-image:management/watcher-ui/images/threshold-alert/threshold-alert-select-action.png["Threshold Alert Select Action",link="management/watcher-ui/images/threshold-alert/threshold-alert-select-action.png"]
-
-Selecting an action will allow you to customize settings for the respective action.
-
-image:management/watcher-ui/images/threshold-alert/threshold-alert-action.png["Threshold Alert Logging Action",link="management/watcher-ui/images/threshold-alert/threshold-alert-action.png"]
-
-All fields for an alert support using http://mustache.github.io/mustache.5.html[mustache syntax] and expose a `{{ctx}}` variable which exposes {stack-ov}/condition-script.html#accessing-watch-payload[various properties of the alert]
-
-The supported actions are:
-
-* {stack-ov}/actions-slack.html[Slack]
-* {stack-ov}/actions-logging.html[Logging]
-* {stack-ov}/actions-email.html[Email]
-
-Note that certain actions require configuration within {es}, such as 
-{stack-ov}/actions-email.html#configuring-email[email] and 
-{stack-ov}/actions-slack.html#configuring-slack[slack].
-
-include::create-advanced-watch.asciidoc[]
+In this example, you set the threshold to 25% so you can see the watch fire. In 
+a  real-world scenario, this threshold is likely too low because the alerts are 
+so frequent. Once you are done experimenting, you should delete the alert. 
+Find the alert on the Watcher overview page and click the trash icon in the *Actions* column.
 
+[float]
+==== Edit the alert
 
+Alternatively, you can keep the alert and adjust the threshold value. To edit 
+an alert, find the alert on the Watcher overview page and click the pencil icon 
+in the *Actions* column. 

docs/management/watcher-ui/getting-started.asciidoc

@@ -1,32 +0,0 @@
-[[watcher-getting-started]]
-=== Getting Started
-
-To use the {watcher} UI, you need to create users with {watcher} specific roles 
-as <<watcher-security,described here>>.
-
-To access {watcher} UI within {kib}:
-
-. Open {kib} in your web browser and log in. If you are running {kib}
-locally, go to `http://localhost:5601/`.
-
-. Click **Management** in the side navigation, then select **Watcher** under `Elasticsearch`.
-+
-[role="screenshot"]
-image::images/management-watcher-buttons.png["Watch list",link="management/watcher-ui/images/watches.png"]
-
-The watch list page within {watcher} UI enables you to view all existing watches including stateful information about each watch. This includes `State`, `Last Fired` and `Last Triggered`.
-
-The possible states for watches are:
-
-* `Firing` - The watch is currently triggered and is actively performing the associated actions.
-* `Error` - The watch is an error state and not properly working.
-* `Ok` - The watch is not actively firing but working properly.
-* `Disabled` - The watch will not fire under any circumstance.
-
-To delete or edit a watch, click on its checkbox in the list and then click the Delete or Edit button. Watches that do not have a checkbox are <<cluster-alerts,cluster alerts>> created by {monitoring} and are immutable.
-
-This page also allows you to create a <<watcher-create-threshold-alert, threshold alert>> or <<watcher-create-advanced-watch, an advanced watch>>. Let's first look at creating a threshold alert.
-
-include::create-threshold-alert.asciidoc[]
-
-include::security.asciidoc[]

docs/management/watcher-ui/index.asciidoc

@@ -1,8 +1,57 @@
 [role="xpack"]
 [[watcher-ui]]
-== Watcher UI
+== Watcher
+
+Watcher is an {es} feature that you can use to create actions based on 
+conditions, which are periodically evaluated using queries on your data. 
+Watches are helpful for analyzing mission-critical and business-critical 
+streaming data. For example, you might watch application logs for performance 
+outages or audit access logs for security threats.
+
+With the Watcher UI, you can:
+
+* Create a simple threshold watch
+* View your watch history and action status
+* Edit, deactivate, and delete a watch
+* Create more advanced watches using API syntax
+
+[role="screenshot"]
+image:management/watcher-ui/images/watches.png["Watcher list"]
+
+{stack-ov}/xpack-alerting.html[Alerting on cluster and index events]
+is a good source for detailed 
+information on how watches work. If you are using the UI to create a 
+threshold watch, take a look at the different watcher actions. If you are 
+creating an advanced watch, you should be familiar with the parts of a 
+watch—input, schedule, condition, and actions.
+
+[float]
+[[watcher-security]]
+=== Watcher security
+
+If the {es} {security-features} are enabled, you must have the
+{stack-ov}/security-privileges.html[`manage_watcher` or `monitor_watcher`]
+cluster privileges to use Watcher in {kib}.
+
+Alternately, you can have the built-in `kibana_user` role
+and either of these watcher roles:
+
+* `watcher_admin`. You can perform all Watcher actions, including create and edit watches.
+* `watcher_user`. You can view watches, but not create or edit them.
+
+You can manage roles in *Management > Security > Roles*, or use the 
+<<role-management-api, Kibana Role Management API>>. Watches are shared between 
+all users with the same role.  
+
+NOTE: If you are creating a threshold watch, you must also have index management 
+privileges.  See 
+<<managing-indices, Managing Indices>> for detailed information.
+
+
+include::create-threshold-alert.asciidoc[]
+include::watcher-getting-started.asciidoc[]
+include::create-advanced-watch.asciidoc[]
+
+
 
-_Watcher UI_ enables you to monitor, manage, create and simulate 
-{stack-ov}/xpack-alerting.html[watches] for your Elasticsearch indices.
 
-include::getting-started.asciidoc[]

docs/management/watcher-ui/security.asciidoc

@@ -1,10 +0,0 @@
-[[watcher-security]]
-=== Watcher UI Security
-
-The Watcher UI requires a user with `kibana_user` and the user must have either `watcher_admin` _or_ `watcher_user`.
-
-`watcher_admin` can perform all watcher-related actions, such as creating a new watch or editing an existing one.
-
-`watcher_user` can view all existing watches, but is not able to create or edit watches.
-
-Learn more about creating users and roles in <<xpack-security>>.

docs/management/watcher-ui/watcher-getting-started.asciidoc

@@ -0,0 +1,46 @@
+[role="xpack"]
+[[watcher-getting-started]]
+=== View watch history and status
+The Watcher overview page lists your watches and includes details such as state,
+last fired, and last triggered.  A watch has one of four states:
+
+* *Firing.* The watch is triggered and actively performing the associated actions.
+* *Error.* The watch is not working properly.
+* *OK.* The watch is not actively firing but working properly.
+* *Disabled.* The watch will not fire under any circumstances.
+
+From this page you can drill down into a watch to investigate its history
+and status.  
+
+[float]
+==== View watch history
+
+The *Execution history* tab shows each time the watch is triggered and the 
+results of the query, whether the condition was met, and what actions were taken. 
+
+[role="screenshot"]
+image:management/watcher-ui/images/execution-history.png["Execution history tab"]
+
+[float]
+==== Acknowledge action status
+
+The *Action statuses* tab lists all actions associated with the watch and 
+the state of each action. If the action is firing, you can acknowledge the 
+watch to prevent too many executions of the same action for the same watch. 
+See {stack-ov}/actions.html#actions-ack-throttle[Acknowledgement and Throttling] for details. 
+
+[role="screenshot"]
+image:management/watcher-ui/images/alerts-status.png["Action status tab"]
+
+[float]
+==== Deactivate and delete a watch
+
+Actions for deactivating and deleting a watch are on each watch detail page:
+
+* *Deactivate a watch* if you know a situation is planned that will 
+cause a false alarm. You can reactivate the watch when the situation is resolved. 
+* *Delete a watch* to permanently remove it from the system. You can delete 
+the watch you are currently viewing, or go to the Watcher overview, and 
+delete watches in bulk. 
+
+