You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: deploy-manage/deploy/elastic-cloud/restrictions-known-problems.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,9 +75,9 @@ Watcher encryption Key Setup is not supported.
75
75
76
76
Changing the default throttle period is not possible. You can specify a throttle period per watch, however.
77
77
78
-
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)
78
+
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)
79
79
80
-
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)
80
+
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)
81
81
82
82
83
83
## Private Link and SSO to Kibana URLs [ec-restrictions-traffic-filters-kibana-sso]
Copy file name to clipboardExpand all lines: explore-analyze/alerts-cases/watcher.md
+28-14Lines changed: 28 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,26 +12,40 @@ mapped_urls:
12
12
13
13
# Watcher
14
14
15
-
% What needs to be done: Lift-and-shift
15
+
::::{tip}
16
+
{{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).
17
+
::::
16
18
17
-
% Use migrated content from existing pages that map to this page:
19
+
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:
* 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.
22
+
* 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.
23
+
* Track network activity to detect malicious activity, and proactively change firewall configuration to reject the malicious user.
24
+
* Monitor Elasticsearch, and send immediate notification to the system administrator if nodes leave the cluster or query throughput exceeds an expected range.
25
+
* 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.
24
26
25
-
% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc):
27
+
All of these use-cases share a few key properties:
26
28
27
-
$$$watcher-create-advanced-watch$$$
29
+
* The relevant data or changes in data can be identified with a periodic Elasticsearch query.
30
+
* The results of the query can be checked against a condition.
31
+
* 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.
28
32
29
-
$$$ec-cloud-email-service-limits$$$
33
+
## How watches work [_how_watches_work]
30
34
31
-
$$$ec-watcher-custom-mail-server$$$
35
+
The {{alert-features}} provide an API for creating, managing and testing *watches*. A watch describes a single alert and can contain multiple notification actions.
32
36
33
-
$$$watcher-create-threshold-alert$$$
37
+
A watch is constructed from four simple building blocks:
34
38
35
-
$$$watcher-deactivate$$$
39
+
Schedule
40
+
: A schedule for running a query and checking the condition.
36
41
37
-
$$$watcher-getting-started$$$
42
+
Query
43
+
: The query to run as input to the condition. Watches support the full Elasticsearch query language, including aggregations.
44
+
45
+
Condition
46
+
: 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.
47
+
48
+
Actions
49
+
: One or more actions, such as sending email, pushing data to 3rd party systems through a webhook, or indexing the results of the query.
50
+
51
+
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.
# Adding conditions to actions [action-conditions]
13
11
14
-
15
12
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.
16
13
17
14
```console
@@ -67,5 +64,3 @@ PUT _watcher/watch/log_event_watch
67
64
```
68
65
69
66
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).
Use the `email` action to send email notifications. To send email, you must [configure at least one email account](#configuring-email) in `elasticsearch.yml`.
16
13
17
14
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.
@@ -42,8 +39,6 @@ For example, the following email action uses a template to include data from the
42
39
4. The subject of the email can contain static text and Mustache [templates](how-watcher-works.md#templates).
43
40
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.
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.
@@ -111,8 +106,6 @@ You can use the `reporting` attachment type in an `email` action to automaticall
111
106
112
107
See [Automating report generation](../../report-and-share/automating-report-generation.md).
{{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).
@@ -151,7 +143,8 @@ You configure the accounts {{watcher}} can use to send email in the `xpack.notif
151
143
152
144
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.
153
145
154
-
$$$email-profile$$$
146
+
### Email profiles [email-profile]
147
+
155
148
{{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.
156
149
157
150
For more information about configuring {{watcher}} to work with different email systems, see:
@@ -161,7 +154,7 @@ For more information about configuring {{watcher}} to work with different email
161
154
*[Sending email from Microsoft Exchange](#exchange)
162
155
*[Sending email from Amazon SES (Simple Email Service)](#amazon-ses)
163
156
164
-
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.
157
+
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.
165
158
166
159
```yaml
167
160
xpack.notification.email:
@@ -173,8 +166,7 @@ xpack.notification.email:
173
166
...
174
167
```
175
168
176
-
177
-
#### Sending email from Gmail [gmail]
169
+
### Sending email from Gmail [gmail]
178
170
179
171
Use the following email account settings to send email from the [Gmail](https://mail.google.com) SMTP service:
180
172
@@ -200,8 +192,7 @@ If you get an authentication error that indicates that you need to continue the
200
192
201
193
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.
202
194
203
-
204
-
#### Sending email from Outlook.com [outlook]
195
+
#### Sending email from Outlook.com [outlook]
205
196
206
197
Use the following email account settings to send email action from the [Outlook.com](https://www.outlook.com/) SMTP service:
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.
227
218
228
-
::::{note}
219
+
::::{note}
229
220
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.
230
221
::::
231
222
232
-
233
-
234
-
#### Sending email from Amazon SES (Simple Email Service) [amazon-ses]
223
+
#### Sending email from Amazon SES (Simple Email Service) [amazon-ses]
235
224
236
225
Use the following email account settings to send email from the [Amazon Simple Email Service](http://aws.amazon.com/ses) (SES) SMTP service:
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.
264
252
::::
265
253
266
-
267
-
268
-
#### Sending email from Microsoft Exchange [exchange]
254
+
#### Sending email from Microsoft Exchange [exchange]
269
255
270
256
Use the following email account settings to send email action from Microsoft Exchange:
1. Some organizations configure Exchange to validate that the `from` field is a valid local email account.
287
273
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.
288
274
289
-
290
275
To store the account SMTP password, use the keystore command (see [secure settings](../../../deploy-manage/security/secure-settings.md))
#### Configuring HTML sanitization options [email-html-sanitization]
281
+
#### Configuring HTML sanitization options [email-html-sanitization]
298
282
299
283
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.
300
284
@@ -313,5 +297,3 @@ To disable sanitization entirely, add the following setting to `elasticsearch.ym
Use the `index` action to index data into Elasticsearch. See [Index action attributes](#index-action-attributes) for the supported attributes.
16
13
17
14
## Configuring index actions [_configuring_index_actions]
@@ -37,8 +34,6 @@ The following snippet shows a simple `index` action definition:
37
34
4. The index, alias, or data stream to which the data will be written
38
35
5. An optional `_id` for the document
39
36
40
-
41
-
42
37
## Index action attributes [index-action-attributes]
43
38
44
39
| Name | Required | Default | Description |
@@ -50,7 +45,6 @@ The following snippet shows a simple `index` action definition:
50
45
|`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. |
51
46
|`refresh`| no | - | Optional setting of the [refresh policy](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-refresh.html) for the write request |
52
47
53
-
54
48
## Multi-document support [anatomy-actions-index-multi-doc-support]
55
49
56
50
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.
@@ -90,6 +84,3 @@ The following snippet shows a multi-document `index` action definition:
90
84
3. A new `severity` field derived from the original document
91
85
4. The payload `_doc` field which is an array of documents
92
86
5. Since the `_index` was informed per document this should be empty
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`.
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.
62
57
63
-
::::{note}
58
+
::::{note}
64
59
The `project.key` (or `project.id`), the `issuetype.name` (or `issuetype.id`) and `issue.summary` are always required to create an issue in Jira.
65
60
::::
66
61
67
-
68
62
| Name | Required | Description |
69
63
| --- | --- | --- |
70
64
|`account`| no | The Jira account to use to send the message. |
@@ -81,7 +75,6 @@ The `project.key` (or `project.id`), the `issuetype.name` (or `issuetype.id`) an
81
75
|`fields.environment`| no | Name of the environment related to the issue. |
82
76
|`fields.customfield_XXX`| no | Custom field XXX of the issue (ex: "customfield_10000": "09/Jun/81") |
83
77
84
-
85
78
## Configuring Jira accounts [configuring-jira]
86
79
87
80
You configure the accounts {{watcher}} can use to communicate with Jira in the `xpack.notification.jira` namespace in `elasticsearch.yml`.
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.
99
91
100
92
::::
101
93
102
-
103
94
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:
104
95
105
-
::::{note}
96
+
::::{note}
106
97
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.
107
98
::::
108
99
109
-
110
100
```yaml
111
101
xpack.notification.jira:
112
102
account:
113
103
monitoring:
114
104
allow_http: true
115
105
```
116
106
117
-
::::{warning}
107
+
::::{warning}
118
108
It is strongly advised to use Basic Authentication with secured HTTPS protocol only.
119
109
::::
120
110
121
-
122
111
You can also specify defaults for the [Jira issues](https://www.elastic.co/guide/en/elasticsearch/reference/current/notification-settings.html#jira-account-attributes):
123
112
124
113
```yaml
@@ -134,7 +123,7 @@ xpack.notification.jira:
134
123
labels: ["auto"]
135
124
```
136
125
137
-
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.
126
+
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.
Use the `logging` action to log text to the standard Elasticsearch logs. See [Logging action attributes](#logging-action-attributes) for the supported attributes.
16
13
17
14
This action is primarily used during development and for debugging purposes.
@@ -37,14 +34,10 @@ The following snippet shows a simple logging action definition:
37
34
2. An optional [transform](transform.md) to transform the payload before executing the `logging` action.
0 commit comments