[E&A] Refines Watcher

deploy-manage/deploy/elastic-cloud/restrictions-known-problems.md

@@ -75,9 +75,9 @@ Watcher encryption Key Setup is not supported.
 
 Changing the default throttle period is not possible. You can specify a throttle period per watch, however.
 
-Watcher comes preconfigured with a directly usable email account provided by Elastic. However, this account can’t be reconfigured and is subject to some limitations. For more information on the limits of the Elastic mail server, check the [cloud email service limits](../../../explore-analyze/alerts-cases/watcher.md#ec-cloud-email-service-limits)
+Watcher comes preconfigured with a directly usable email account provided by Elastic. However, this account can’t be reconfigured and is subject to some limitations. For more information on the limits of the Elastic mail server, check the [cloud email service limits](../../../explore-analyze/alerts-cases/watcher/enable-watcher.md#cloud-email-service-limits)
 
-Alternatively, a custom mail server can be configured as described in [Configuring a custom mail server](../../../explore-analyze/alerts-cases/watcher.md#ec-watcher-custom-mail-server)
+Alternatively, a custom mail server can be configured as described in [Configuring a custom mail server](../../../explore-analyze/alerts-cases/watcher/enable-watcher.md#watcher-custom-mail-server)
 
 
 ## Private Link and SSO to Kibana URLs [ec-restrictions-traffic-filters-kibana-sso]

explore-analyze/alerts-cases/watcher.md

@@ -9,26 +9,40 @@ mapped_urls:
 
 # Watcher
 
-% What needs to be done: Lift-and-shift
+::::{tip}
+{{kib}} Alerting provides a set of built-in actions and alerts that are integrated with applications such as APM, Metrics, Security, and Uptime. You can use {{kib}} Alerting to detect complex conditions within different {{kib}} apps and trigger actions when those conditions are met. For more information, refer to [Alerts and Cases](../alerts-cases.md).
+::::
 
-% Use migrated content from existing pages that map to this page:
+You can use Watcher to watch for changes or anomalies in your data and perform the necessary actions in response. For example, you might want to:
 
-% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/xpack-alerting.md
-% - [ ] ./raw-migrated-files/cloud/cloud/ec-watcher.md
-% - [ ] ./raw-migrated-files/kibana/kibana/watcher-ui.md
-% - [ ] ./raw-migrated-files/docs-content/serverless/elasticsearch-differences.md
-% - [ ] ./raw-migrated-files/kibana/kibana/secure-reporting.md
+* 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.
 
-% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc):
+All of these use-cases share a few key properties:
 
-$$$watcher-create-advanced-watch$$$
+* 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.
 
-$$$ec-cloud-email-service-limits$$$
+## How watches work [_how_watches_work]
 
-$$$ec-watcher-custom-mail-server$$$
+The {{alert-features}} provide an API for creating, managing and testing *watches*. A watch describes a single alert and can contain multiple notification actions.
 
-$$$watcher-create-threshold-alert$$$
+A watch is constructed from four simple building blocks:
 
-$$$watcher-deactivate$$$
+Schedule
+:   A schedule for running a query and checking the condition.
 
-$$$watcher-getting-started$$$
+Query
+:   The query to run as input to the condition. Watches support the full Elasticsearch query language, including aggregations.
+
+Condition
+:   A condition that determines whether or not to execute the actions. You can use simple conditions (always true), or use scripting for more sophisticated scenarios.
+
+Actions
+:   One or more actions, such as sending email, pushing data to 3rd party systems through a webhook, or indexing the results of the 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.

explore-analyze/alerts-cases/watcher/action-conditions.md

@@ -4,11 +4,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/action-conditions.html
 ---
 
-
-
 # Adding conditions to actions [action-conditions]
 
-
 When a watch is triggered, its condition determines whether or not to execute the watch actions. Within each action, you can also add a condition per action. These additional conditions enable a single alert to execute different actions depending on a their respective conditions. The following watch would always send an email, when hits are found from the input search, but only trigger the `notify_pager` action when there are more than 5 hits in the search result.
 
 ```console
@@ -64,5 +61,3 @@ PUT _watcher/watch/log_event_watch
 ```
 
 1. A `condition` that only applies to the `notify_pager` action, which restricts its execution to when the condition succeeds (at least 5 hits in this case).
-
-

explore-analyze/alerts-cases/watcher/action-foreach.md

@@ -41,5 +41,3 @@ PUT _watcher/watch/log_event_watch
 ```
 
 1. The logging statement will be executed for each of the returned search hits.
-
-

explore-analyze/alerts-cases/watcher/actions-email.md

@@ -4,11 +4,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/actions-email.html
 ---
 
-
-
 # Email action [actions-email]
 
-
 Use the `email` action to send email notifications. To send email, you must [configure at least one email account](#configuring-email) in `elasticsearch.yml`.
 
 Email notifications can be plain text or styled using HTML. You can include information from the watch execution payload using [templates](how-watcher-works.md#templates) and attach the entire watch payload to the message.
@@ -39,8 +36,6 @@ For example, the following email action uses a template to include data from the
 4. The subject of the email can contain static text and Mustache [templates](how-watcher-works.md#templates).
 5. The body of the email can contain static text and Mustache [templates](how-watcher-works.md#templates). Must be specified in the action definition or in the email account configuration.
 
-
-
 ## Configuring email attachments [configuring-email-attachments]
 
 You can attach the execution context payload or data from an any HTTP service to the email notification. There is no limit on the number of attachments you can configure.
@@ -108,8 +103,6 @@ You can use the `reporting` attachment type in an `email` action to automaticall
 
 See [Automating report generation](../../report-and-share/automating-report-generation.md).
 
-
-
 ## Email action attributes [email-action-attributes]
 
 | Name | Required | Default | Description |
@@ -139,7 +132,6 @@ $$$address-list$$$
 Address List
 :   A list of addresses can be specified as a an array: `[ 'Personal Name <[email protected]>', '[email protected]' ]`.
 
-
 ## Configuring email accounts [configuring-email]
 
 {{watcher}} can send email using any SMTP email service. Email messages can contain basic HTML tags. You can control which groups of tags are allowed by [Configuring HTML Sanitization Options](#email-html-sanitization).
@@ -148,7 +140,8 @@ You configure the accounts {{watcher}} can use to send email in the `xpack.notif
 
 If your email account is configured to require two step verification, you need to generate and use a unique App Password to send email from {{watcher}}. Authentication will fail if you use your primary password.
 
-$$$email-profile$$$
+### Email profiles [email-profile]
+
 {{watcher}} provides three email profiles that control how MIME messages are structured: `standard` (default), `gmail`, and `outlook`. These profiles accommodate differences in how various email systems interpret the MIME standard. If you are using Gmail or Outlook, we recommend using the corresponding profile. Use the `standard` profile if you are using another email system.
 
 For more information about configuring {{watcher}} to work with different email systems, see:
@@ -158,7 +151,7 @@ For more information about configuring {{watcher}} to work with different email
 * [Sending email from Microsoft Exchange](#exchange)
 * [Sending email from Amazon SES (Simple Email Service)](#amazon-ses)
 
-If you configure multiple email accounts, you must either configure a default account or specify which account the email should be sent with in the [`email`]() action.
+If you configure multiple email accounts, you must either configure a default account or specify which account the email should be sent with in the `email` action.
 
 ```yaml
 xpack.notification.email:
@@ -170,8 +163,7 @@ xpack.notification.email:
       ...
 ```
 
-
-#### Sending email from Gmail [gmail] 
+### Sending email from Gmail [gmail]
 
 Use the following email account settings to send email from the [Gmail](https://mail.google.com) SMTP service:
 
@@ -197,8 +189,7 @@ If you get an authentication error that indicates that you need to continue the
 
 If two-step verification is enabled for your account, you must generate and use a unique App Password to send email from {{watcher}}. See [Sign in using App Passwords](https://support.google.com/accounts/answer/185833?hl=en) for more information.
 
-
-#### Sending email from Outlook.com [outlook] 
+#### Sending email from Outlook.com [outlook]
 
 Use the following email account settings to send email action from the [Outlook.com](https://www.outlook.com/) SMTP service:
 
@@ -222,13 +213,11 @@ bin/elasticsearch-keystore add xpack.notification.email.account.outlook_account.
 
 When sending emails, you have to provide a from address, either a default one in your account configuration or as part of the email action in the watch.
 
-::::{note} 
+::::{note}
 You need to use a unique App Password if two-step verification is enabled. See [App passwords and two-step verification](http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification) for more information.
 ::::
 
-
-
-#### Sending email from Amazon SES (Simple Email Service) [amazon-ses] 
+#### Sending email from Amazon SES (Simple Email Service) [amazon-ses]
 
 Use the following email account settings to send email from the [Amazon Simple Email Service](http://aws.amazon.com/ses) (SES) SMTP service:
 
@@ -249,20 +238,17 @@ xpack.notification.email.account:
 1. In certain cases `email_defaults.from` is validated by Amazon SES to ensure that it is a valid local email account.
 2. `smtp.host` varies depending on the region.
 
-
 To store the account SMTP password, use the keystore command (see [secure settings](../../../deploy-manage/security/secure-settings.md))
 
 ```yaml
 bin/elasticsearch-keystore add xpack.notification.email.account.ses_account.smtp.secure_password
 ```
 
-::::{note} 
+::::{note}
 You need to use your Amazon SES SMTP credentials to send email through Amazon SES. For more information, see [Obtaining Your Amazon SES SMTP Credentials](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.md). You might also need to verify [your email address](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.md) or [your whole domain](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.md) at AWS.
 ::::
 
-
-
-#### Sending email from Microsoft Exchange [exchange] 
+#### Sending email from Microsoft Exchange [exchange]
 
 Use the following email account settings to send email action from Microsoft Exchange:
 
@@ -283,15 +269,13 @@ xpack.notification.email.account:
 1. Some organizations configure Exchange to validate that the `from` field is a valid local email account.
 2. Many organizations support use of your email address as your username, though it is a good idea to check with your system administrator if you receive authentication-related failures.
 
-
 To store the account SMTP password, use the keystore command (see [secure settings](../../../deploy-manage/security/secure-settings.md))
 
 ```yaml
 bin/elasticsearch-keystore add xpack.notification.email.account.exchange_account.smtp.secure_password
 ```
 
-
-#### Configuring HTML sanitization options [email-html-sanitization] 
+#### Configuring HTML sanitization options [email-html-sanitization]
 
 The `email` action supports sending messages with an HTML body. However, for security reasons, {{watcher}} [sanitizes](https://en.wikipedia.org/wiki/HTML_sanitization) the HTML.
 
@@ -310,5 +294,3 @@ To disable sanitization entirely, add the following setting to `elasticsearch.ym
 ```yaml
 xpack.notification.email.html.sanitization.enabled: false
 ```
-
-

explore-analyze/alerts-cases/watcher/actions-index.md

@@ -4,11 +4,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/actions-index.html
 ---
 
-
-
 # Index action [actions-index]
 
-
 Use the `index` action to index data into Elasticsearch. See [Index action attributes](#index-action-attributes) for the supported attributes.
 
 ## Configuring index actions [_configuring_index_actions]
@@ -34,8 +31,6 @@ The following snippet shows a simple `index` action definition:
 4. The index, alias, or data stream to which the data will be written
 5. An optional `_id` for the document
 
-
-
 ## Index action attributes [index-action-attributes]
 
 | Name | Required | Default | Description |
@@ -47,7 +42,6 @@ The following snippet shows a simple `index` action definition:
 | `timeout` | no | 60s | The timeout for waiting for the index api call to                                                      return. If no response is returned within this time,                                                      the index action times out and fails. This setting                                                      overrides the default timeouts. |
 | `refresh` | no | - | Optional setting of the [refresh policy](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-refresh.html)                                                      for the write request |
 
-
 ## Multi-document support [anatomy-actions-index-multi-doc-support]
 
 Like with all other actions, you can use a [transform](transform.md) to replace the current execution context payload with another and by that change the document that will end up indexed.
@@ -87,6 +81,3 @@ The following snippet shows a multi-document `index` action definition:
 3. A new `severity` field derived from the original document
 4. The payload `_doc` field which is an array of documents
 5. Since the `_index` was informed per document this should be empty
-
-
-

explore-analyze/alerts-cases/watcher/actions-jira.md

@@ -4,11 +4,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/actions-jira.html
 ---
 
-
-
 # Jira action [actions-jira]
 
-
 Use the `jira` action to create issues in [Atlassian’s Jira Software](https://www.atlassian.com/software/jira). To create issues you need to [configure at least one Jira account](#configuring-jira) in `elasticsearch.yml`.
 
 ## Configuring Jira actions [configuring-jira-actions]
@@ -51,17 +48,14 @@ The following snippet shows a simple jira action definition:
 6. The labels to apply to the Jira issue.
 7. The priority of the Jira issue.
 
-
-
 ## Jira action attributes [jira-action-attributes]
 
 Depending of how Jira projects are configured, the issues can have many different fields and values. Therefore the `jira` action can accept any type of sub fields within its `issue` field. These fields will be directly used when calling Jira’s [Create Issue API](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-createIssue), allowing any type of custom fields to be used.
 
-::::{note} 
+::::{note}
 The `project.key` (or `project.id`), the `issuetype.name` (or `issuetype.id`) and `issue.summary` are always required to create an issue in Jira.
 ::::
 
-
 | Name | Required | Description |
 | --- | --- | --- |
 | `account` | no | The Jira account to use to send the message. |
@@ -78,7 +72,6 @@ The `project.key` (or `project.id`), the `issuetype.name` (or `issuetype.id`) an
 | `fields.environment` | no | Name of the environment related to the issue. |
 | `fields.customfield_XXX` | no | Custom field XXX of the issue (ex: "customfield_10000": "09/Jun/81") |
 
-
 ## Configuring Jira accounts [configuring-jira]
 
 You configure the accounts {{watcher}} can use to communicate with Jira in the `xpack.notification.jira` namespace in `elasticsearch.yml`.
@@ -90,32 +83,28 @@ bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure
 bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure_user
 bin/elasticsearch-keystore add xpack.notification.jira.account.monitoring.secure_password
 ```
-
-::::{warning} 
+::::{warning}
 Storing sensitive data (`url`, `user` and `password`) in the configuration file or the cluster settings is insecure and has been deprecated. Please use {{es}}'s secure [keystore](../../../deploy-manage/security/secure-settings.md) method instead.
 
 ::::
 
-
 To avoid credentials that transit in clear text over the network, {{watcher}} will reject `url` settings like `http://internal-jira.elastic.co` that are based on plain text HTTP protocol. This default behavior can be disabled with the explicit `allow_http` setting:
 
-::::{note} 
+::::{note}
 The `url` field can also contain a path, that is used to create an issue. By default this is `/rest/api/2/issue`. If you set this as well, make sure that this path is the full path to the endpoint to create an issue.
 ::::
 
-
 ```yaml
 xpack.notification.jira:
   account:
     monitoring:
       allow_http: true
 ```
 
-::::{warning} 
+::::{warning}
 It is strongly advised to use Basic Authentication with secured HTTPS protocol only.
 ::::
 
-
 You can also specify defaults for the [Jira issues](https://www.elastic.co/guide/en/elasticsearch/reference/current/notification-settings.html#jira-account-attributes):
 
 ```yaml
@@ -131,7 +120,7 @@ xpack.notification.jira:
         labels: ["auto"]
 ```
 
-If you configure multiple Jira accounts, you either need to configure a default account or specify which account the notification should be sent with in the [`jira`]() action.
+If you configure multiple Jira accounts, you either need to configure a default account or specify which account the notification should be sent with in the `jira` action.
 
 ```yaml
 xpack.notification.jira:
@@ -142,5 +131,3 @@ xpack.notification.jira:
     team2:
       ...
 ```
-
-

explore-analyze/alerts-cases/watcher/actions-logging.md

@@ -4,11 +4,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/actions-logging.html
 ---
 
-
-
 # Logging action [actions-logging]
 
-
 Use the `logging` action to log text to the standard Elasticsearch logs. See [Logging action attributes](#logging-action-attributes) for the supported attributes.
 
 This action is primarily used during development and for debugging purposes.
@@ -34,14 +31,10 @@ The following snippet shows a simple logging action definition:
 2. An optional [transform](transform.md) to transform the payload before executing the `logging` action.
 3. The text to be logged.
 
-
-
 ## Logging action attributes [logging-action-attributes]
 
 | Name | Required | Default | Description |
 | --- | --- | --- | --- |
 | `text` | yes | - | The text that should be logged. Can be static text or                                                          include Mustache [templates](how-watcher-works.md#templates). |
 | `category` | no | xpack.watcher.actions.logging | The category under which the text will be logged. |
 | `level` | no | info | The logging level. Valid values are: `error`, `warn`,                                                          `info`, `debug` and `trace`. |
-
-