diff --git a/docs/java-rest/high-level/watcher/ack-watch.asciidoc b/docs/java-rest/high-level/watcher/ack-watch.asciidoc index 46a516798594b..2b865cbd2e7cd 100644 --- a/docs/java-rest/high-level/watcher/ack-watch.asciidoc +++ b/docs/java-rest/high-level/watcher/ack-watch.asciidoc @@ -10,7 +10,7 @@ [id="{upid}-{api}-request"] ==== Execution -{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you +{ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you to manually throttle execution of a watch's actions. A watch can be acknowledged through the following request: diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc index 7c342a3da7a5a..75b1a450c0dcd 100644 --- a/docs/painless/painless-contexts.asciidoc +++ b/docs/painless/painless-contexts.asciidoc @@ -49,9 +49,9 @@ specialized code may define new ways to use a Painless script. | Bucket selector aggregation | <> | {ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[Elasticsearch Documentation] | Watcher condition | <> - | {xpack-ref}/condition-script.html[Elasticsearch Documentation] + | {ref}/condition-script.html[Elasticsearch Documentation] | Watcher transform | <> - | {xpack-ref}/transform-script.html[Elasticsearch Documentation] + | {ref}/transform-script.html[Elasticsearch Documentation] |==== include::painless-contexts/painless-context-examples.asciidoc[] diff --git a/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc index 713bcf32daec4..506bc3b967e5a 100644 --- a/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc +++ b/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc @@ -1,7 +1,7 @@ [[painless-watcher-condition-context]] === Watcher condition context -Use a Painless script as a {xpack-ref}/condition-script.html[watcher condition] +Use a Painless script as a {ref}/condition-script.html[watcher condition] to test if a response is necessary. *Variables* @@ -26,7 +26,7 @@ to test if a response is necessary. `ctx['payload']` (`Map`, read-only):: The accessible watch data based upon the - {xpack-ref}/input.html[watch input]. + {ref}/input.html[watch input]. *Return* diff --git a/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc index 27cb4eb15056d..4a2bab6554bbf 100644 --- a/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc +++ b/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc @@ -1,7 +1,7 @@ [[painless-watcher-transform-context]] === Watcher transform context -Use a Painless script to {xpack-ref}/transform-script.html[transform] watch +Use a Painless script to {ref}/transform-script.html[transform] watch data into a new payload for use in a response to a condition. *Variables* @@ -26,7 +26,7 @@ data into a new payload for use in a response to a condition. `ctx['payload']` (`Map`, read-only):: The accessible watch data based upon the - {xpack-ref}/input.html[watch input]. + {ref}/input.html[watch input]. *Return* diff --git a/docs/reference/commands/syskeygen.asciidoc b/docs/reference/commands/syskeygen.asciidoc index 3ae7456448d83..06d8330a1222a 100644 --- a/docs/reference/commands/syskeygen.asciidoc +++ b/docs/reference/commands/syskeygen.asciidoc @@ -21,7 +21,8 @@ bin/elasticsearch-syskeygen The command generates a `system_key` file, which you can use to symmetrically encrypt sensitive data. For example, you can use this key to prevent {watcher} -from returning and storing information that contains clear text credentials. See {xpack-ref}/encrypting-data.html[Encrypting sensitive data in {watcher}]. +from returning and storing information that contains clear text credentials. See +<>. IMPORTANT: The system key is a symmetric key, so the same key must be used on every node in the cluster. diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index e6d7a979f808c..288b402aaeb4b 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -67,6 +67,8 @@ include::rollup/index.asciidoc[] include::frozen-indices.asciidoc[] +include::{xes-repo-dir}/watcher/index.asciidoc[] + include::rest-api/index.asciidoc[] include::commands/index.asciidoc[] diff --git a/docs/reference/release-notes/6.0.asciidoc b/docs/reference/release-notes/6.0.asciidoc index 4a063236c92d8..28657e257a94b 100644 --- a/docs/reference/release-notes/6.0.asciidoc +++ b/docs/reference/release-notes/6.0.asciidoc @@ -1279,8 +1279,7 @@ Security:: Watcher:: * Added verification that the required templates exist before {watcher} starts. -For more information, see -{stack-ov}/how-watcher-works.html#scripts-templates[Scripts and Templates]. +For more information, see <>. * Added the `xpack.watcher.history.cleaner_service.enabled` setting. You can use this setting to enable or disable the cleaner service, which removes previous versions of {watcher} indices (for example, .watcher-history*) when it diff --git a/docs/reference/release-notes/6.2.asciidoc b/docs/reference/release-notes/6.2.asciidoc index 15292b812559f..63b4ba3d7d5a7 100644 --- a/docs/reference/release-notes/6.2.asciidoc +++ b/docs/reference/release-notes/6.2.asciidoc @@ -220,8 +220,7 @@ Watcher:: * Fixed the serialization of failed hipchat messages, such that it no longer tries to write the status field twice. * Fixed TransformInput toXContent serialization errors. For more information, -see -{stack-ov}/input-chain.html#_transforming_chained_input_data[Transforming Chained Input Data]. +see <<_transforming_chained_input_data>>. Allocation:: @@ -434,7 +433,7 @@ more information, see {stack-ov}/saml-realm.html[SAML authentication]. Watcher:: * Added a transform input for chained input. For more information, see -{stack-ov}/input-chain.html#_transforming_chained_input_data[Transforming Chained Input Data]. +<<_transforming_chained_input_data>>. [float] === Enhancements diff --git a/docs/reference/settings/notification-settings.asciidoc b/docs/reference/settings/notification-settings.asciidoc index 500b425fdc3a2..e96e3702a25b6 100644 --- a/docs/reference/settings/notification-settings.asciidoc +++ b/docs/reference/settings/notification-settings.asciidoc @@ -8,10 +8,11 @@ ++++ You configure `xpack.notification` settings in `elasticsearch.yml` to -send set up {watcher} and send notifications via <>, -<>, +send set up {watcher} and send notifications via +<>, +<>, <>, and -<>. Dynamic settings can also be updated +<>. Dynamic settings can also be updated across a cluster with the <>. [float] @@ -23,14 +24,12 @@ Set to `false` to disable {watcher} on the node. `xpack.watcher.encrypt_sensitive_data`:: Set to `true` to encrypt sensitive data. If this setting is enabled, you must also specify the `xpack.watcher.encryption_key` setting. For more -information, see -{stack-ov}/encrypting-data.html[Encrypting sensitive data in {watcher}]. +information, see <>. `xpack.watcher.encryption_key` (<>):: Specifies the path to a file that contains a key for encrypting sensitive data. If `xpack.watcher.encrypt_sensitive_data` is set to `true`, this setting is -required. For more information, see -{stack-ov}/encrypting-data.html[Encrypting sensitive data in {watcher}]. +required. For more information, see <>. `xpack.watcher.history.cleaner_service.enabled`:: ifdef::asciidoctor[] @@ -80,7 +79,7 @@ include::ssl-settings.asciidoc[] ==== Email Notification Settings You can configure the following email notification settings in `elasticsearch.yml`. For more information about sending notifications -via email, see {stack-ov}/actions-email.html#configuring-email-actions[Configuring Email]. +via email, see <>. `xpack.notification.email.account`:: Specifies account information for sending notifications via email. You @@ -90,14 +89,15 @@ can specify the following email account attributes: [[email-account-attributes]] `profile` (<>);; - The {stack-ov}/actions-email.html#configuring-email[email profile] to use to build the MIME + The <> to use to build the MIME messages that are sent from the account. Valid values: `standard`, `gmail` and `outlook`. Defaults to `standard`. `email_defaults.*` (<>);; An optional set of email attributes to use as defaults - for the emails sent from the account. See {stack-ov}/actions-email.html#email-action-attributes[ - Email Action Attributes] for the supported attributes. + for the emails sent from the account. See + <> for the supported + attributes. `smtp.auth` (<>);; Set to `true` to attempt to authenticate the user using the @@ -161,9 +161,9 @@ can specify the following email account attributes: `xpack.notification.email.html.sanitization.allow`:: Specifies the HTML elements that are allowed in email notifications. For -more information, see {stack-ov}/actions-email.html#email-html-sanitization[Configuring HTML -Sanitization Options]. You can specify individual HTML elements -and the following HTML feature groups: +more information, see +<>. You can +specify individual HTML elements and the following HTML feature groups: + -- [[html-feature-groups]] @@ -212,10 +212,10 @@ Defaults to `true`. [float] [[hipchat-notification-settings]] -==== HipChat Notification Settings +==== HipChat notification settings You can configure the following HipChat notification settings in `elasticsearch.yml`. For more information about sending notifications -via HipChat, see {stack-ov}/actions-hipchat.html#configuring-hipchat-actions[Configuring HipChat]. +via HipChat, see <>. `xpack.notification.hipchat` :: Specifies account information for sending notifications @@ -266,7 +266,7 @@ via HipChat. You can specify the following HipChat account attributes: ==== Slack Notification Settings You can configure the following Slack notification settings in `elasticsearch.yml`. For more information about sending notifications -via Slack, see {stack-ov}/actions-slack.html#configuring-slack-actions[Configuring Slack]. +via Slack, see <>. `xpack.notification.slack` :: Specifies account information for sending notifications @@ -310,7 +310,7 @@ via Slack. You can specify the following Slack account attributes: ==== Jira Notification Settings You can configure the following Jira notification settings in `elasticsearch.yml`. For more information about using notifications -to create issues in Jira, see {stack-ov}/actions-jira.html#configuring-jira-actions[Configuring Jira]. +to create issues in Jira, see <>. `xpack.notification.jira` :: Specifies account information for using notifications to create @@ -339,7 +339,7 @@ issues in Jira. You can specify the following Jira account attributes: `issue_defaults`;; Default fields values for the issue created in Jira. See - {stack-ov}/actions-jira.html#jira-action-attributes[Jira Action Attributes] for more information. + <> for more information. Optional. -- @@ -348,7 +348,7 @@ issues in Jira. You can specify the following Jira account attributes: ==== PagerDuty Notification Settings You can configure the following PagerDuty notification settings in `elasticsearch.yml`. For more information about sending notifications -via PagerDuty, see {stack-ov}/actions-pagerduty.html#configuring-pagerduty-actions[Configuring PagerDuty]. +via PagerDuty, see <>. [[pagerduty-account-attributes]] @@ -372,8 +372,9 @@ PagerDuty API key] to use to access PagerDuty. Required. -- + `event_defaults`;; -Default values for {stack-ov}/actions-pagerduty.html#pagerduty-event-trigger-incident-attributes[ -PagerDuty event attributes]. Optional. +Default values for +<>. +Optional. + -- `description`:: diff --git a/docs/reference/setup/bootstrap-checks-xes.asciidoc b/docs/reference/setup/bootstrap-checks-xes.asciidoc index a7b27e3e4e506..3c680fa3cbdb2 100644 --- a/docs/reference/setup/bootstrap-checks-xes.asciidoc +++ b/docs/reference/setup/bootstrap-checks-xes.asciidoc @@ -14,8 +14,7 @@ If you use {watcher} and have chosen to encrypt sensitive data (by setting the secure settings store. To pass this bootstrap check, you must set the `xpack.watcher.encryption_key` -on each node in the cluster. For more information, see -{xpack-ref}/encrypting-data.html[Encrypting Sensitive Data in {watcher}]. +on each node in the cluster. For more information, see <>. [float] === PKI realm check diff --git a/x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc b/x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc index 3b3550ac61f90..620b213eb74da 100644 --- a/x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc @@ -5,7 +5,7 @@ Ack watch ++++ -{stack-ov}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you +<> enables you to manually throttle execution of the watch's actions. An action's _acknowledgement state_ is stored in the `status.actions..ack.state` structure. diff --git a/x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc b/x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc index b1770b66aa591..6ed21812d9ec5 100644 --- a/x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc @@ -5,8 +5,7 @@ Activate watch ++++ -A watch can be either -{stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This +A watch can be either <>. This API enables you to activate a currently inactive watch. [float] diff --git a/x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc b/x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc index 8ef501941c187..f1499b527f151 100644 --- a/x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc @@ -5,8 +5,7 @@ Deactivate watch ++++ -A watch can be either -{stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This +A watch can be either <>. This API enables you to deactivate a currently active watch. [float] diff --git a/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc b/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc index 52700a112f61f..81c448ac56c82 100644 --- a/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc @@ -59,14 +59,14 @@ This API supports the following fields: that will be used during the watch execution | `ignore_condition` | no | false | When set to `true`, the watch execution uses the - {stack-ov}/condition-always.html[Always Condition]. + <>. This can also be specified as an HTTP parameter. | `alternative_input` | no | null | When present, the watch uses this object as a payload instead of executing its own input. | `action_modes` | no | null | Determines how to handle the watch actions as part of the - watch execution. See <> + watch execution. See <> for more information. | `record_execution` | no | false | When set to `true`, the watch record representing the watch @@ -75,8 +75,7 @@ This API supports the following fields: watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter. -| `watch` | no | null | When present, this - {stack-ov}/how-watcher-works.html#watch-definition[watch] is used +| `watch` | no | null | When present, this <> is used instead of the one specified in the request. This watch is not persisted to the index and record_execution cannot be set. |====== @@ -94,7 +93,7 @@ are five possible modes an action can be associated with: | `simulate` | The action execution is simulated. Each action type define its own simulation operation mode. For example, the - {stack-ov}/actions-email.html[email] action creates + <> creates the email that would have been sent but does not actually send it. In this mode, the action might be throttled if the current state of the watch indicates it should be. diff --git a/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc b/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc index ea784852cbb4c..ee8e7e6e33544 100644 --- a/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc @@ -27,7 +27,7 @@ IMPORTANT: Putting a watch must be done via this API only. Do not put a watch privileges are granted to anyone over the `.watches` index. When adding a watch you can also define its initial -{xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that +<>. You do that by setting the `active` parameter. [float] @@ -52,16 +52,16 @@ A watch has the following fields: |====== | Name | Description -| `trigger` | The {xpack-ref}/trigger.html[trigger] that defines when +| `trigger` | The <> that defines when the watch should run. -| `input` | The {xpack-ref}/input.html[input] that defines the input +| `input` | The <> that defines the input that loads the data for the watch. -| `condition` | The {xpack-ref}/condition.html[condition] that defines if +| `condition` | The <> that defines if the actions should be run. -| `actions` | The list of {xpack-ref}/actions.html[actions] that will be +| `actions` | The list of <> that will be run if the condition matches | `metadata` | Metadata json that will be copied into the history entries. @@ -75,7 +75,7 @@ A watch has the following fields: ==== Authorization You must have `manage_watcher` cluster privileges to use this API. For more -information, see {xpack-ref}/security-privileges.html[Security Privileges]. +information, see {stack-ov}/security-privileges.html[Security Privileges]. [float] ==== Security Integration @@ -148,7 +148,7 @@ PUT _xpack/watcher/watch/my-watch // CONSOLE When you add a watch you can also define its initial -{xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that +<>. You do that by setting the `active` parameter. The following command adds a watch and sets it to be inactive by default: diff --git a/x-pack/docs/en/watcher/actions.asciidoc b/x-pack/docs/en/watcher/actions.asciidoc index de2516b0589cc..d3b147b8231da 100644 --- a/x-pack/docs/en/watcher/actions.asciidoc +++ b/x-pack/docs/en/watcher/actions.asciidoc @@ -2,7 +2,7 @@ == Actions When a watch's condition is met, its actions are executed unless it is being -<>. A watch can perform multiple actions. +<>. A watch can perform multiple actions. The actions are executed one at a time and each action executes independently. Any failures encountered while executing an action are recorded in the action result and in the watch history. @@ -15,13 +15,13 @@ support their execution in any way they need. For example, the payload might serve as a model for a templated email body. {watcher} supports the following types of actions: -<>, <>, <>, -<>, <>, <>, and <>. +<>, <>, <>, +<>, <>, +and <>. [float] [[actions-ack-throttle]] -=== Acknowledgement and Throttling +=== Acknowledgement and throttling During the watch execution, once the condition is met, a decision is made per configured action as to whether it should be throttled. The main purpose of @@ -93,7 +93,7 @@ PUT _xpack/watcher/watch/error_logs_alert // CONSOLE <1> There will be at least 15 minutes between subsequent `email_administrator` action executions. -<2> See <> for more information. +<2> See <> for more information. You can also define a throttle period at the watch level. The watch-level throttle period serves as the default throttle period for all of the actions @@ -165,15 +165,14 @@ xpack.watcher.execution.default_throttle_period: 15m -------------------------------------------------- {watcher} also supports acknowledgement-based throttling. You can acknowledge a -watch using the {ref}/watcher-api-ack-watch.html[Ack Watch API] to prevent the +watch using the <> to prevent the watch actions from being executed again while the watch condition remains `true`. This essentially tells {watcher} "I received the notification and I'm handling it, please do not notify me about this error again". An acknowledged watch action remains in the `acked` state until the watch's condition evaluates to `false`. When that happens, the action's state changes to `awaits_successful_execution`. -To acknowledge an action, you use the -{ref}/watcher-api-ack-watch.html[Ack Watch API]: +To acknowledge an action, you use the <>: [source,js] ---------------------------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/email.asciidoc b/x-pack/docs/en/watcher/actions/email.asciidoc index 9ec65a070df12..9f1e53608b1a9 100644 --- a/x-pack/docs/en/watcher/actions/email.asciidoc +++ b/x-pack/docs/en/watcher/actions/email.asciidoc @@ -1,5 +1,5 @@ [[actions-email]] -=== Email Action +=== Email action Use the `email` action to send email notifications. To send email, you must <> in @@ -15,7 +15,7 @@ account configuration. The required attributes must either be set in the email action definition or the account's `email_defaults`. [[configuring-email-actions]] -==== Configuring Email Actions +==== Configuring email actions You configure email actions in the `actions` array. Action-specific attributes are specified using the `email` keyword. @@ -47,7 +47,7 @@ the watch payload in the email body: account configuration. [[configuring-email-attachments]] -==== 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 @@ -151,20 +151,15 @@ killed by firewalls or load balancers in-between. [[email-action-reports]] -===== Attaching Reports to an Email +===== Attaching reports to an email You can use the `reporting` attachment type in an `email` action to automatically generate a Kibana report and distribute it via email. -include::{kib-repo-dir}/reporting/watch-example.asciidoc[] - -include::{kib-repo-dir}/reporting/report-intervals.asciidoc[] - -For more information, see -{kibana-ref}/automating-report-generation.html[Automating Report Generation]. +See {kibana-ref}/automating-report-generation.html[Automating report generation]. [[email-action-attributes]] -==== Email Action Attributes +==== Email action attributes [cols=",^,,", options="header"] |====== @@ -251,7 +246,7 @@ A list of addresses can be specified as a an array: `[ 'Personal Name ', 'user2@host.domain' ]`. [[configuring-email]] -==== Configuring Email Accounts +==== Configuring email accounts {watcher} can send email using any SMTP email service. Email messages can contain basic HTML tags. You can control which groups of tags are @@ -280,14 +275,14 @@ email system. For more information about configuring {watcher} to work with different email systems, see: -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> 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 -<> action. +<> action. [source,yaml] -------------------------------------------------- @@ -302,7 +297,7 @@ xpack.notification.email: [float] [[gmail]] -===== Sending Email From Gmail +===== Sending email from Gmail Use the following email account settings to send email from the https://mail.google.com[Gmail] SMTP service: @@ -340,7 +335,7 @@ for more information. [float] [[outlook]] -===== Sending Email from Outlook.com +===== Sending email from Outlook.com Use the following email account settings to send email action from the https://www.outlook.com/[Outlook.com] SMTP service: @@ -376,7 +371,7 @@ NOTE: You need to use a unique App Password if two-step verification is enable [float] [[amazon-ses]] -===== Sending Email from Amazon SES (Simple Email Service) +===== Sending email from Amazon SES (Simple Email Service) Use the following email account settings to send email from the http://aws.amazon.com/ses[Amazon Simple Email Service] (SES) SMTP service: @@ -413,7 +408,7 @@ NOTE: You need to use your Amazon SES SMTP credentials to send email through [float] [[exchange]] -===== Sending Email from Microsoft Exchange +===== Sending email from Microsoft Exchange Use the following email account settings to send email action from Microsoft Exchange: @@ -448,7 +443,7 @@ bin/elasticsearch-keystore xpack.notification.email.account.exchange_account.smt [float] [[email-html-sanitization]] -===== Configuring HTML Sanitization Options +===== Configuring HTML sanitization options The `email` action supports sending messages with an HTML body. However, for security reasons, {watcher} https://en.wikipedia.org/wiki/HTML_sanitization[sanitizes] diff --git a/x-pack/docs/en/watcher/actions/hipchat.asciidoc b/x-pack/docs/en/watcher/actions/hipchat.asciidoc index 49799567410ea..30bb1374ad3b6 100644 --- a/x-pack/docs/en/watcher/actions/hipchat.asciidoc +++ b/x-pack/docs/en/watcher/actions/hipchat.asciidoc @@ -1,12 +1,12 @@ [[actions-hipchat]] -=== HipChat Action +=== HipChat action Use the `hipchat` action to send messages to https://www.hipchat.com[HipChat] rooms or users. To send HipChat messages, you must -<> in `elasticsearch.yml`. +<> in `elasticsearch.yml`. [[configuring-hipchat-actions]] -==== Configuring HipChat Actions +==== Configuring HipChat actions You configure HipChat actions in a `actions` array. Action-specific attributes are specified using the `hipchat` keyword. You must specify the `message` @@ -15,7 +15,7 @@ message is sent using the default HipChat account configured in `elasticsearch.yml`. For example, the following action is configured to send messages using a HipChat -account that uses the <> profile. Because +account that uses the <> profile. Because this type of account can only send messages to a specific room, the only required attribute is the message itself: @@ -41,7 +41,7 @@ attribute is the message itself: <1> The name of a HipChat account configured in `elasticsearch.yml`. <2> The message you want to send to HipChat. -To send messages with a HipChat account that uses the <> +To send messages with a HipChat account that uses the <> profile, you need to specify what rooms and users you want to send the message to. For example, the following action is configured to send messages to the `mission-control` and `devops` rooms as well as the user `website-admin@example.com`. @@ -69,7 +69,7 @@ For example, the following action is configured to send messages to the -------------------------------------------------- // NOTCONSOLE -To send messages with a HipChat account that uses the <> +To send messages with a HipChat account that uses the <> profile, you need to specify what room or rooms you want to send the message to. For example, the following action is configured to send messages to the `server-status` room. (To send to multiple rooms, specify an array of strings.) @@ -97,7 +97,7 @@ For example, the following action is configured to send messages to the // NOTCONSOLE [[hipchat-action-attributes]] -==== HipChat Action Attributes +==== HipChat action attributes [cols=",^,,", options="header"] |====== @@ -136,7 +136,7 @@ For example, the following action is configured to send messages to the [[configuring-hipchat]] -==== Configuring HipChat Accounts +==== Configuring HipChat accounts You configure the accounts {watcher} can use to communicate with HipChat in the `xpack.notification.hipchat` namespace in `elasticsearch.yml`. Both @@ -165,11 +165,11 @@ NOTE: The `v1` profile is provided because it is simple to set up and this API If you configure multiple HipChat accounts, you either need to set a default HipChat account or specify which account the notification should be sent with -in the <> action. +in the <> action. Storing the `auth_token` in the configuration file or using via updating the settings now is still supported, but you should use the keystore for this, see -{ref}/secure-settings.html[secure settings] +<>. [source,yaml] -------------------------------------------------- @@ -184,7 +184,7 @@ xpack.notification.hipchat: [[hipchat-api-integration]] -===== Using the Hipchat Integration Profile +===== Using the Hipchat integration profile You can use the `integration` profile to send messages to specific rooms. When you set an account's profile to `integration`, the messages are sent through @@ -194,11 +194,11 @@ Send room notification] API. When you use the `integration` profile, you need to configure a separate HipChat account for each room you want to send messages--the account configuration contains a room-specific authentication token. Alternatively, you can use the -<> or <> profile to send messages +<> or <> profile to send messages to multiple rooms. NOTE: The `integration` profile only supports sending messages to rooms, it does - not support sending private messages. Use the <> + not support sending private messages. Use the <> profile to notify a particular HipChat user. You need a room-specific authentication token to configure an `integration` @@ -242,8 +242,8 @@ xpack.notification.hipchat: room: monitoring -------------------------------------------------- -You can also specify defaults for the {ref}/notification-settings.html#hipchat-account-attributes[ -message attributes]: +You can also specify defaults for the +<>: [source,yaml] -------------------------------------------------- @@ -260,7 +260,7 @@ xpack.notification.hipchat: [[hipchat-api-user]] -===== Using the HipChat User Profile +===== Using the HipChat user profile You can use the `user` profile to send messages to rooms as well as individual HipChat users. When you set an account's profile to `user`, {watcher} sends @@ -307,8 +307,8 @@ xpack.notification.hipchat: profile: user -------------------------------------------------- -You can also specify defaults for the <{ref}/notification-settings.html#hipchat-account-attributes[ -message attributes]: +You can also specify defaults for the +<>: [source,shell] -------------------------------------------------- @@ -329,7 +329,7 @@ xpack.notification.hipchat: [[hipchat-api-v1]] -===== Using the HipChat v1 Profile +===== Using the HipChat v1 profile You can use the `v1` profile to send messages to particular rooms. When you set an account's profile to `v1`, messages are sent through HipChat's v1 @@ -339,7 +339,7 @@ WARNING: The `v1` profile uses a deprecated API that is expected to be removed by HipChat in the future. The `v1` profile only supports sending messages to rooms, it does not support -sending private messages. Use the <> profile to send +sending private messages. Use the <> profile to send private messages to HipChat users. Before you can configure a `v1` account, you need to generate a `v1` API token: @@ -379,8 +379,8 @@ xpack.notification.hipchat: profile: v1 -------------------------------------------------- -You can also specify defaults for the {ref}/notification-settings.html#hipchat-account-attributes[ -message attributes]. +You can also specify defaults for the +<>. [source,yaml] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/index.asciidoc b/x-pack/docs/en/watcher/actions/index.asciidoc index 8a31b150f22cb..4e54956cc79e8 100644 --- a/x-pack/docs/en/watcher/actions/index.asciidoc +++ b/x-pack/docs/en/watcher/actions/index.asciidoc @@ -1,10 +1,10 @@ [[actions-index]] -=== Index Action +=== Index action Use the `index` action to index data into Elasticsearch. See <> for the supported attributes. -==== Configuring Index Actions +==== Configuring index actions The following snippet shows a simple `index` action definition: @@ -24,15 +24,15 @@ The following snippet shows a simple `index` action definition: -------------------------------------------------- // NOTCONSOLE <1> The id of the action -<2> An optional <> to restrict action execution -<3> An optional <> to transform the payload and prepare the data that should be indexed +<2> An optional <> to restrict action execution +<3> An optional <> to transform the payload and prepare the data that should be indexed <4> The elasticsearch index to store the data to <5> The document type to store the data as <6> An optional `_id` for the document, if it should always be the same document. [[index-action-attributes]] -==== Index Action Attributes +==== Index action attributes [options="header"] |====== @@ -58,7 +58,7 @@ The following snippet shows a simple `index` action definition: |====== [[anatomy-actions-index-multi-doc-support]] -==== Multi-Document Support +==== Multi-document support Like with all other actions, you can use a <> to replace the current execution context payload with another and by that change the document diff --git a/x-pack/docs/en/watcher/actions/jira.asciidoc b/x-pack/docs/en/watcher/actions/jira.asciidoc index 7d50a75df3fa3..e13bc15f701ae 100644 --- a/x-pack/docs/en/watcher/actions/jira.asciidoc +++ b/x-pack/docs/en/watcher/actions/jira.asciidoc @@ -1,11 +1,11 @@ [[actions-jira]] -=== Jira Action +=== Jira action Use the `jira` action to create issues in https://www.atlassian.com/software/jira[Atlassian's Jira Software]. To create issues you need to <> in `elasticsearch.yml`. [[configuring-jira-actions]] -==== Configuring Jira Actions +==== Configuring Jira actions You configure Jira actions in the `actions` array. Action-specific attributes are specified using the `jira` keyword. @@ -48,7 +48,7 @@ The following snippet shows a simple jira action definition: <7> The priority of the Jira issue. [[jira-action-attributes]] -==== 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 @@ -99,7 +99,7 @@ always required to create an issue in Jira. |====== [[configuring-jira]] -==== Configuring Jira Accounts +==== Configuring Jira accounts You configure the accounts {watcher} can use to communicate with Jira in the `xpack.notification.jira` namespace in `elasticsearch.yml`. @@ -138,7 +138,7 @@ WARNING: It is strongly advised to use Basic Authentication with secured HTTPS protocol only. You can also specify defaults for the -{ref}/notification-settings.html#jira-account-attributes[Jira issues]: +<>: [source,yaml] -------------------------------------------------- @@ -156,7 +156,7 @@ xpack.notification.jira: 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 -<> action. +<> action. [source,yaml] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/logging.asciidoc b/x-pack/docs/en/watcher/actions/logging.asciidoc index a8a4454c377eb..9493f18dce29a 100644 --- a/x-pack/docs/en/watcher/actions/logging.asciidoc +++ b/x-pack/docs/en/watcher/actions/logging.asciidoc @@ -1,5 +1,5 @@ [[actions-logging]] -=== Logging Action +=== Logging action Use the `logging` action to log text to the standard Elasticsearch logs. See <> for the supported attributes. @@ -7,7 +7,7 @@ logs. See <> for the supported attributes. This action is primarily used during development and for debugging purposes. [[configuring-logging-actions]] -==== Configuring Logging Actions +==== Configuring logging actions You configure logging actions in the `actions` array. Action-specific attributes are specified using the `logging` keyword. @@ -33,7 +33,7 @@ The following snippet shows a simple logging action definition: [[logging-action-attributes]] -==== Logging Action Attributes +==== Logging action attributes [options="header"] |====== diff --git a/x-pack/docs/en/watcher/actions/pagerduty.asciidoc b/x-pack/docs/en/watcher/actions/pagerduty.asciidoc index f7ae06ad9648d..1969bf8d0943d 100644 --- a/x-pack/docs/en/watcher/actions/pagerduty.asciidoc +++ b/x-pack/docs/en/watcher/actions/pagerduty.asciidoc @@ -1,12 +1,12 @@ [[actions-pagerduty]] -=== PagerDuty Action +=== PagerDuty action Use the PagerDuty action to create events in https://pagerduty.com/[ PagerDuty]. To create PagerDuty events, you must <> in `elasticsearch.yml`. [[configuring-pagerduty-actions]] -==== Configuring PagerDuty Actions +==== Configuring PagerDuty actions You configure PagerDuty actions in the `actions` array. Action-specific attributes are specified using the `pagerduty` keyword. @@ -30,7 +30,7 @@ The following snippet shows a simple PagerDuty action definition: [[adding-context-and-payloads-to-pagerduty-actions]] -==== Adding Meta Information to a PagerDuty Incident +==== Adding meta information to a PagerDuty incident To give the PagerDuty incident some more context, you can attach the payload as well as an array of contexts to the action. @@ -64,7 +64,7 @@ payload as well as an array of contexts to the action. [[pagerduty-action-attributes]] -==== Pagerduty Action Attributes +==== Pagerduty action attributes [cols=",^,", options="header"] |====== @@ -75,7 +75,7 @@ payload as well as an array of contexts to the action. [[pagerduty-event-trigger-incident-attributes]] -.Pagerduty Event Trigger Incident Attributes +.Pagerduty event trigger incident attributes [cols=",^,", options="header"] |====== | Name |Required | Description @@ -114,7 +114,7 @@ NOTE: All of those objects have templating support, so you can use data from the context and the payload as part of all the fields. [[pagerduty-event-trigger-context-attributes]] -.Pagerduty Event Trigger Context Attributes +.Pagerduty event trigger context attributes [cols=",^,", options="header"] |====== | Name |Required | Description @@ -128,7 +128,7 @@ NOTE: All of those objects have templating support, so you can use data from the |====== [[configuring-pagerduty]] -==== Configuring PagerDuty Accounts +==== Configuring PagerDuty accounts You configure the accounts {watcher} uses to communicate with PagerDuty in the `xpack.notification.pagerduty` namespace in `elasticsearch.yml`. @@ -148,7 +148,7 @@ image::images/pagerduty-services.jpg[] image::images/pagerduty-integrations.jpg[] To configure a PagerDuty account in the keystore, you -must specify an account name and integration key, (see {ref}/secure-settings.html[secure settings]): +must specify an account name and integration key, (see <>): [source,yaml] -------------------------------------------------- @@ -158,8 +158,8 @@ bin/elasticsearch-keystore add xpack.notification.pagerduty.account.my_pagerduty Storing the service api key in the YAML file or via cluster update settings is still supported, but the keystore setting should be used -You can also specify defaults for the <>: +You can also specify defaults for the +<>: . [source,yaml] @@ -178,7 +178,7 @@ xpack.notification.pagerduty: If you configure multiple PagerDuty accounts, you either need to set a default account or specify which account the event should be sent with in the -<> action. +<> action. [source,yaml] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/slack.asciidoc b/x-pack/docs/en/watcher/actions/slack.asciidoc index 05ee7b7b340d9..7dad9ea8c9fc1 100644 --- a/x-pack/docs/en/watcher/actions/slack.asciidoc +++ b/x-pack/docs/en/watcher/actions/slack.asciidoc @@ -1,13 +1,13 @@ [[actions-slack]] -=== Slack Action +=== Slack action Use the `slack` action to send messages to a https://slack.com/[Slack] team's channels or users. To send Slack messages, you need to -<> in +<> in `elasticsearch.yml`. [[configuring-slack-actions]] -==== Configuring Slack Actions +==== Configuring Slack actions You configure Slack actions in the `actions` array. Action-specific attributes are specified using the `slack` keyword. @@ -35,7 +35,7 @@ The following snippet shows a simple slack action definition: [[formatting-slack-messages]] -==== Using Attachments to Format Slack Messages +==== Using attachments to format Slack messages In addition to sending simple text-based messages, you can use the Slack https://api.slack.com/docs/attachments[attachment] mechanism to send formatted @@ -139,7 +139,7 @@ aggregation and the Slack action: generated by the transform. [[slack-action-attributes]] -==== Slack Action Attributes +==== Slack action attributes [cols=",^,", options="header"] |====== @@ -167,7 +167,7 @@ aggregation and the Slack action: | `message.dynamic_attachments` | no | Slack message attachments that can be populated dynamically based on the current watch payload. For more information, see - <>. + <>. | `proxy.host` | no | The proxy host to use (only in combination with `proxy.port`) @@ -207,8 +207,8 @@ You can also configure this via settings in the `elasticsearch.yml` file by removing the `secure_` prefix, but using the keystore is the preferred and secure way of doing this. -You can also specify defaults for the {ref}/notification-settings.html#slack-account-attributes[Slack -notification attributes]: +You can also specify defaults for the +<>: [source,yaml] -------------------------------------------------- @@ -230,7 +230,7 @@ xpack.notification.slack: If you configure multiple Slack accounts, you either need to configure a default account or specify which account the notification should be sent with in the -<> action. +<> action. [source,yaml] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/webhook.asciidoc b/x-pack/docs/en/watcher/actions/webhook.asciidoc index 5d6dc4f91fce1..0ab4fe8227564 100644 --- a/x-pack/docs/en/watcher/actions/webhook.asciidoc +++ b/x-pack/docs/en/watcher/actions/webhook.asciidoc @@ -1,13 +1,12 @@ [[actions-webhook]] -=== Webhook Action +=== Webhook action Use the `webhook` action to send a request to any web service. The webhook action supports both HTTP and HTTPS connections. See -<> for the supported -attributes. +<> for the supported attributes. [[configuring-webook-actions]] -==== Configuring Webhook Actions +==== Configuring webhook actions You configure webhook actions in the `actions` array. Action-specific attributes are specified using the `webhook` keyword. @@ -32,9 +31,9 @@ The following snippet shows a simple webhook action definition: -------------------------------------------------- // NOTCONSOLE <1> The id of the action -<2> An optional <> to transform the payload before +<2> An optional <> to transform the payload before executing the `webhook` action -<3> An optional <> for the action +<3> An optional <> for the action (5 minutes in this example) <4> The HTTP method to use when connecting to the host <5> The host to connect to @@ -76,8 +75,9 @@ NOTE: By default, both the username and the password are stored in the `.watches You can also use PKI-based authentication when submitting requests to a cluster that has {es} {security-features} enabled. When you use PKI-based authentication instead of HTTP basic auth, you don't need to store any authentication -information in the watch itself. To use PKI-based authentication, you {ref}/notification-settings.html#ssl-notification-settings -[configure the SSL key settings] for {watcher} in `elasticsearch.yml`. +information in the watch itself. To use PKI-based authentication, you +<> for {watcher} in +`elasticsearch.yml`. [[webhook-query-parameters]] @@ -135,7 +135,7 @@ the values serve as the header values: <1> The header values can contain templated strings. -==== Webhook Action Attributes +==== Webhook action attributes [[webhook-action-attributes]] [cols=",^,^,", options="header"] |====== @@ -148,23 +148,23 @@ the values serve as the header values: | `port` | yes | - | The port the HTTP service is listening on. | `path` | no | - | The URL path. The path can be static text or include Mustache - <>. URL query string parameters must be + <>. URL query string parameters must be specified via the `request.params` attribute. | `method` | no | get | The HTTP method. Valid values are: `head`, `get`, `post`, `put` and `delete`. | `headers` | no | - | The HTTP request headers. The header values can be static text - or include Mustache <>. + or include Mustache <>. | `params` | no | - | The URL query string parameters. The parameter values can be - static text or include Mustache <>. + static text or include Mustache <>. | `auth` | no | - | Authentication related HTTP headers. Currently, only basic authentication is supported. | `body` | no | - | The HTTP request body. The body can be static text or include - Mustache <>. When not specified, an empty + Mustache <>. When not specified, an empty body is sent. | `proxy.host` | no | - | The proxy host to use when connecting to the host. diff --git a/x-pack/docs/en/watcher/condition.asciidoc b/x-pack/docs/en/watcher/condition.asciidoc index 01f55f9b6682a..40d15c8c74ac6 100644 --- a/x-pack/docs/en/watcher/condition.asciidoc +++ b/x-pack/docs/en/watcher/condition.asciidoc @@ -4,29 +4,29 @@ When a watch is triggered, its condition determines whether or not to execute the watch actions. {watcher} supports the following condition types: -* <>: set the watch condition to `true` so the watch +* <>: set the watch condition to `true` so the watch actions are always executed. -* <>: set the watch condition to `false` so the watch +* <>: set the watch condition to `false` so the watch actions are never executed. -* <>: perform simple comparisons against values +* <>: perform simple comparisons against values in the watch payload to determine whether or not to execute the watch actions. -* <>: compare an array of values in the +* <>: compare an array of values in the watch payload to a given value to determine whether or not to execute the watch actions. -* <>: use a script to determine whether or not to +* <>: use a script to determine whether or not to execute the watch actions. NOTE: If you omit the condition definition from a watch, the condition defaults to `always`. When a condition is evaluated, it has full access to the watch execution context, -including the watch payload (`ctx.payload.*`). The <>, -<> and <> +including the watch payload (`ctx.payload.*`). The <>, +<> and <> conditions can use the payload data to determine whether or not the necessary conditions are met. In addition to the watch wide condition, you can also configure conditions -per <>. +per <>. :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/watcher/condition/always.asciidoc include::condition/always.asciidoc[] diff --git a/x-pack/docs/en/watcher/condition/always.asciidoc b/x-pack/docs/en/watcher/condition/always.asciidoc index c2eb37be52c8f..81026af092682 100644 --- a/x-pack/docs/en/watcher/condition/always.asciidoc +++ b/x-pack/docs/en/watcher/condition/always.asciidoc @@ -1,14 +1,14 @@ [[condition-always]] -=== Always Condition +=== Always condition Use the `always` condition to set the condition to `true`. This forces the watch -actions to be executed unless they are <>. +actions to be executed unless they are <>. The `always` condition enables you to perform watch actions on a fixed schedule, such as, _"Every Friday at noon, send a status report email to sys.admin@example.com."_ -==== Using the Always Condition +==== Using the always condition This is the default if you omit the condition definition from a watch. diff --git a/x-pack/docs/en/watcher/condition/array-compare.asciidoc b/x-pack/docs/en/watcher/condition/array-compare.asciidoc index e82eaf5384061..fcca9c660a695 100644 --- a/x-pack/docs/en/watcher/condition/array-compare.asciidoc +++ b/x-pack/docs/en/watcher/condition/array-compare.asciidoc @@ -1,19 +1,19 @@ [[condition-array-compare]] -=== Array Compare Condition +=== Array compare condition Use `array_compare` to compare an array of values in the execution context to a -given value. See <> +given value. See <> for the operators you can use. -==== Using an Array Compare Condition +==== Using an array compare condition To use the `array_compare` condition, you specify the array in the execution -context that you want to evaluate, a <>, and the value you want to compare against. Optionally, you -can specify the path to the field in each array element that you want to -evaluate. +context that you want to evaluate, a +<>, and the value you want to +compare against. Optionally, you can specify the path to the field in each array +element that you want to evaluate. For example, the following `array_compare` condition returns `true` if there is at least one bucket in the aggregation that has a `doc_count` greater @@ -38,14 +38,14 @@ than or equal to 25: <1> The path to the array in the execution context that you want to evaluate, specified in dot notation. <2> The path to the field in each array element that you want to evaluate. -<3> The <> to use. +<3> The <> to use. <4> The comparison value. Supports date math like the - <>. + <>. NOTE: When using fieldnames that contain a dot this condition will not work, use a <> instead. -==== Array-Compare Condition Attributes +==== Array-compare condition attributes [options="header"] |====== diff --git a/x-pack/docs/en/watcher/condition/compare.asciidoc b/x-pack/docs/en/watcher/condition/compare.asciidoc index d58638e6fe472..5741732fb014f 100644 --- a/x-pack/docs/en/watcher/condition/compare.asciidoc +++ b/x-pack/docs/en/watcher/condition/compare.asciidoc @@ -1,12 +1,12 @@ [[condition-compare]] -=== Compare Condition +=== Compare condition Use the `compare` condition to perform a simple comparison against a value in the watch payload. You can use the `compare` condition without enabling dynamic scripting. [[condition-compare-operators]] -. Supported Comparison Operators +. Supported comparison operators [options="header"] |====== | Name | Description @@ -30,13 +30,13 @@ dynamic scripting. given one (applies to numeric and string values) |====== -==== Using a Compare Condition +==== Using a compare condition To use the `compare` condition, you specify the value in the execution context that you want to evaluate, a <>, and the value you want to compare against. For example, the following `compare` -condition returns `true` if the number of the total hits in the <> is greater than or equal to 5: +condition returns `true` if the number of the total hits in the +<> is greater than or equal to 5: [source,js] -------------------------------------------------- @@ -89,7 +89,7 @@ to the `ctx.payload.aggregations.handled.buckets.true.doc_count`: -------------------------------------------------- // NOTCONSOLE -==== Accessing Values in the Execution Context +==== Accessing values in the execution context You use "dot-notation" to access values in the execution context. Values loaded into the execution context by the input are prefixed by `ctx.payload`. diff --git a/x-pack/docs/en/watcher/condition/never.asciidoc b/x-pack/docs/en/watcher/condition/never.asciidoc index b8cad0b8c04d5..e7aa2745d75ad 100644 --- a/x-pack/docs/en/watcher/condition/never.asciidoc +++ b/x-pack/docs/en/watcher/condition/never.asciidoc @@ -1,12 +1,12 @@ [[condition-never]] -=== Never Condition +=== Never condition Use the `never` condition to set the condition to `false`. This means the watch actions are never executed when the watch is triggered. The watch input is executed, a record is added to the watch history, and the watch execution ends. This condition is generally used for testing. -==== Using the Never Condition +==== Using the never condition There are no attributes to specify for the `never` condition. To use the it, you specify the condition type and associate it with an empty object: diff --git a/x-pack/docs/en/watcher/condition/script.asciidoc b/x-pack/docs/en/watcher/condition/script.asciidoc index 5e94551a5ef17..a69ae05509fb6 100644 --- a/x-pack/docs/en/watcher/condition/script.asciidoc +++ b/x-pack/docs/en/watcher/condition/script.asciidoc @@ -1,14 +1,13 @@ [[condition-script]] -=== Script Condition +=== Script condition -A watch <> that evaluates a script. The default scripting +A watch <> that evaluates a script. The default scripting language is `painless`. You can use any of the scripting languages supported by Elasticsearch as long as the language supports evaluating expressions to Boolean values. Note that the `mustache` and `expression` languages are too limited to be -used by this condition. For more information, see {ref}/modules-scripting.html[Scripting] -in the Elasticsearch Reference. +used by this condition. For more information, see <>. -==== Using a Script Condition +==== Using a script condition The following snippet configures an inline `script` condition that always returns `true`: @@ -22,11 +21,11 @@ The following snippet configures an inline `script` condition that always return // NOTCONSOLE This example defines a script as a simple string. This format is actually a -shortcut for defining an <> script. The +shortcut for defining an <> script. The formal definition of a script is an object that specifies the script type and optional language and parameter values. If the `lang` attribute is omitted, the language defaults to `painless`. Elasticsearch supports two types of scripts, -<> and <>. +<> and <>. For example, the following snippet shows a formal definition of an `inline` script that explicitly specifies the language and defines a single script @@ -47,7 +46,7 @@ parameter, `result`: // NOTCONSOLE [[condition-script-inline]] -==== Inline Scripts +==== Inline scripts Inline scripts are scripts that are defined in the condition itself. The following snippet shows the formal configuration of a simple painless script that @@ -64,10 +63,11 @@ always returns `true`. // NOTCONSOLE [[condition-script-stored]] -==== Stored Scripts +==== Stored scripts -Stored scripts refer to scripts that were {ref}/modules-scripting-using.html#modules-scripting-stored-scripts[stored] -in Elasticsearch. The following snippet shows how to refer to a script by its `id`: +Stored scripts refer to scripts that were +<> in Elasticsearch. The following +snippet shows how to refer to a script by its `id`: [source,js] -------------------------------------------------- @@ -79,8 +79,8 @@ in Elasticsearch. The following snippet shows how to refer to a script by its `i -------------------------------------------------- // NOTCONSOLE -As with <> -scripts, you can also specify the script language and parameters: +As with <> scripts, you can also specify the +script language and parameters: [source,js] -------------------------------------------------- @@ -95,14 +95,14 @@ scripts, you can also specify the script language and parameters: // NOTCONSOLE [[accessing-watch-payload]] -==== Accessing the Watch Payload +==== Accessing the watch payload A script can access the current watch execution context, including the payload data, as well as any parameters passed in through the condition definition. -For example, the following snippet defines a watch that uses a <> -and uses a `script` condition to check if the number of hits is above a specified -threshold: +For example, the following snippet defines a watch that uses a +<> and uses a `script` condition to check if the +number of hits is above a specified threshold: [source,js] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/customizing-watches.asciidoc b/x-pack/docs/en/watcher/customizing-watches.asciidoc index 34b9c38229f4b..edc88e3e68bff 100644 --- a/x-pack/docs/en/watcher/customizing-watches.asciidoc +++ b/x-pack/docs/en/watcher/customizing-watches.asciidoc @@ -1,29 +1,30 @@ [[customizing-watches]] -== Customizing Watches +== Customizing watches -Now that you've seen how to set up simple watches to <> -and <>, let's take a closer -look at how you can customize a watch by modifying its <>, -<>, <>, and -<>. +Now that you've seen how to set up simple watches to +<> and +<>, let's take a closer +look at how you can customize a watch by modifying its <>, +<>, <>, and +<>. [[changing-inputs]] -=== Changing Inputs +=== Changing inputs The Watch Input is called when the watch triggered to load an initial payload. This payload is stored in the _Watch Execution Context_ and from then on is available for other watch elements to access (e.g. watch conditions can be evaluated based on the data in this payload). -{watcher} supports four types of inputs <>, -<>, <>, and -<>. +{watcher} supports four types of inputs <>, +<>, <>, and +<>. [[loading-static-data]] -==== Loading a Static Payload with the Simple Input +==== Loading a static payload with the simple input To load static data into the watch payload for testing purposes, you can use the -<> input. For example, the following input stores three +<> input. For example, the following input stores three fields in the payload: [source,js] @@ -41,13 +42,13 @@ fields in the payload: See <> for more details. [[loading-search-results]] -==== Loading a Payload from Elasticsearch with the Search Input +==== Loading a payload from Elasticsearch with the search input You can use the `search` input to load Elasticsearch search results as the watch initial payload. -A <> input contains a `request` object that specifies the -indices you want to search, the {ref}/search-request-search-type.html[search type], +A <> input contains a `request` object that specifies the +indices you want to search, the <>, and the search request body. The `body` field of a search input is the same as the body of an Elasticsearch `_search` request, making the full Elaticsearch Query DSL available for you to use. @@ -81,7 +82,7 @@ For example, the following `search` input loads the latest VIX quote: See <> for more details. [[loading-http-data]] -==== Loading a Payload from a remote HTTP Service with HTTP Input +==== Loading a payload from a remote HTTP service with HTTP input Use the `http` input to issue an HTTP request and load the returned response as the watch initial payload. This input expects the response body content type @@ -111,28 +112,28 @@ Amsterdam using http://openweathermap.org/appid[OpenWeatherMap] online service: See <> for more details. [[chaining-inputs]] -==== Chaining Inputs +==== Chaining inputs -You can create an <> to load data from multiple sources +You can create an <> to load data from multiple sources into a watch payload. The inputs in a chain are processed in order, so the the data loaded by one input can be used by subsequent inputs. See <> for more details. [[changing-conditions]] -=== Changing Conditions +=== Changing conditions The Watch Condition is evaluated as part of the watch execution. The condition determines whether the actions associated with the watch should execute or not. -{watcher} supports four types of conditions <>, -<>, <>, and -<>. +{watcher} supports four types of conditions <>, +<>, <>, and +<>. The first two are pretty self-explanatory--they are shortcuts for setting a watch's condition to `true` or `false`. -==== Simple Value Comparison with the Compare Condition +==== Simple value comparison with the compare condition The `compare` condition enables you to perform simple comparisons against values in the Watch payload. While you can also do this with a `script` condition, with @@ -151,7 +152,7 @@ returned any hits: // NOTCONSOLE See <> for more details. -==== Powerful Comparison Logic with the Script Condition +==== Powerful comparison logic with the script condition For more complex conditional logic you can use the `script` condition. The `script` condition accepts a script that when executed returns `true` (indicating @@ -160,7 +161,7 @@ language defaults to the default script language in Elasticsearch, but you can also use any other supported language in the system. NOTE: Starting with 5.0, Elasticsearch is shipped with the new - {ref}/modules-scripting-painless.html[Painless] scripting language. + <> scripting language. Painless was created and designed specifically for use in Elasticsearch. Beyond providing an extensive feature set, its biggest trait is that it's properly sandboxed and safe to use anywhere in the system (including in @@ -182,13 +183,13 @@ VIX quote loaded by the `http` input is either greater than 5% or lower than -5% See <> for more details. [[using-transforms]] -=== Using Transforms +=== Using transforms Transforms are constructs in a watch that can change the current payload associated with the watch execution context. -{watcher} supports three types of transforms <>, -<> and <>. A `search` transform +{watcher} supports three types of transforms <>, +<> and <>. A `search` transform replaces the existing payload with the response of a new search request. You can use `script` transforms to modify the existing payload. A `chain` transform enables you to perform a series of `search` and `script` transforms. @@ -196,19 +197,19 @@ enables you to perform a series of `search` and `script` transforms. See <> for more details. [[customizing-actions]] -=== Customizing Actions +=== Customizing actions Actions are associated with a watch and are executed as part of the watch execution only when the watch condition is met. -{watcher} supports the following action types: <>, -<>, <>, <>, -<>, <>, and <>. +{watcher} supports the following action types: <>, +<>, <>, <>, +<>, <>, and <>. -To use the `email` action, you need to <> +To use the `email` action, you need to <> in `elasticsearch.yml` that {watcher} can use to send email. Your custom email messages can be plain text or styled using HTML. You can include information from -the watch execution payload using <>, as well as attach the +the watch execution payload using <>, as well as attach the entire watch payload to the message. For example, the following email action uses a template in the email body and diff --git a/x-pack/docs/en/watcher/encrypting-data.asciidoc b/x-pack/docs/en/watcher/encrypting-data.asciidoc index 66138b54efba2..8c5e012fa55e7 100644 --- a/x-pack/docs/en/watcher/encrypting-data.asciidoc +++ b/x-pack/docs/en/watcher/encrypting-data.asciidoc @@ -1,5 +1,5 @@ [[encrypting-data]] -== Encrypting Sensitive Data in {watcher} +== Encrypting sensitive data in {watcher} Watches might have access to sensitive data such as HTTP basic authentication information or details about your SMTP email service. You can encrypt this @@ -14,7 +14,7 @@ encrypted. To encrypt sensitive data in {watcher}: -. Use the {ref}/syskeygen.html[elasticsearch-syskeygen] command to create a system key file. +. Use the <> command to create a system key file. . Copy the `system_key` file to all of the nodes in your cluster. + @@ -24,8 +24,7 @@ every node in the cluster. -- -. Set the -{ref}/notification-settings.html[`xpack.watcher.encrypt_sensitive_data` setting]: +. Set the <>: + -- @@ -36,8 +35,8 @@ xpack.watcher.encrypt_sensitive_data: true -- . Set the -{ref}/notification-settings.html[`xpack.watcher.encryption_key` setting] in the -{ref}/secure-settings.html[{es} keystore] on each node in the cluster. +<> in the +<> on each node in the cluster. + -- For example, run the following command to import the `system_key` file on diff --git a/x-pack/docs/en/watcher/example-watches.asciidoc b/x-pack/docs/en/watcher/example-watches.asciidoc index 2a402b20261d7..4f3b0564fd1b0 100644 --- a/x-pack/docs/en/watcher/example-watches.asciidoc +++ b/x-pack/docs/en/watcher/example-watches.asciidoc @@ -1,13 +1,13 @@ [[example-watches]] -== Example Watches +== Example watches The following examples show how to set up watches to: -* <> -* <> +* <> +* <> For more example watches you can use as a starting point for building custom watches, see the https://github.com/elastic/examples/tree/master/Alerting[Example -Watches] in the Elastic Examples repo. +watches] in the Elastic Examples repo. :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc include::example-watches/example-watch-clusterstatus.asciidoc[] diff --git a/x-pack/docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc b/x-pack/docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc index 0add5d99ccd2a..47653a90f63bf 100644 --- a/x-pack/docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc +++ b/x-pack/docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc @@ -1,23 +1,23 @@ [[watch-cluster-status]] -=== Watching the Status of an Elasticsearch Cluster +=== Watching the status of an Elasticsearch cluster You can easily configure a basic watch to monitor the health of your Elasticsearch cluster: -* <> that gets the +* <> that gets the cluster health status. -* <> that evaluates the health status to +* <> that evaluates the health status to determine if action is required. -* <> if the cluster is RED. +* <> if the cluster is RED. [float] [[health-add-input]] -==== Schedule the Watch and Add an Input +==== Schedule the watch and add an input -A watch <> controls how often a watch is triggered. -The watch <> gets the data that you want to evaluate. +A watch <> controls how often a watch is triggered. +The watch <> gets the data that you want to evaluate. The simplest way to define a schedule is to specify an interval. For example, the following schedule runs every 10 seconds: @@ -48,7 +48,7 @@ GET _cluster/health?pretty // TEST[continued] To load the health status into your watch, you simply add an -<> that calls the cluster health API: +<> that calls the cluster health API: [source,js] -------------------------------------------------- @@ -70,7 +70,8 @@ PUT _xpack/watcher/watch/cluster_health_watch -------------------------------------------------- // CONSOLE -If you're using Security, then you'll also need to supply some authentication credentials as part of the watch configuration: +If you're using Security, then you'll also need to supply some authentication +credentials as part of the watch configuration: [source,js] -------------------------------------------------- @@ -98,9 +99,12 @@ PUT _xpack/watcher/watch/cluster_health_watch -------------------------------------------------- // CONSOLE -It would be a good idea to create a user with the minimum privileges required for use with such a watch configuration. +It would be a good idea to create a user with the minimum privileges required +for use with such a watch configuration. -Depending on how your cluster is configured, there may be additional settings required before the watch can access your cluster such as keystores, truststores or certificates. For more information, see {ref}/notification-settings.html[Notification Settings]. +Depending on how your cluster is configured, there may be additional settings +required before the watch can access your cluster such as keystores, truststores, +or certificates. For more information, see <>. If you check the watch history, you'll see that the cluster status is recorded @@ -123,9 +127,9 @@ GET .watcher-history*/_search [float] [[health-add-condition]] -==== Add a Condition +==== Add a condition -A <> evaluates the data you've loaded into the watch and +A <> evaluates the data you've loaded into the watch and determines if any action is required. Since you've defined an input that loads the cluster status into the watch, you can define a condition that checks that status. @@ -178,11 +182,11 @@ GET .watcher-history*/_search?pretty [float] [[health-take-action]] -==== Take Action +==== Take action Recording `watch_records` in the watch history is nice, but the real power of {watcher} is being able to do something in response to an alert. A watch's -<> define what to do when the watch condition is true--you +<> define what to do when the watch condition is true--you can send emails, call third-party webhooks, or write documents to an Elasticsearch index or log when the watch condition is met. @@ -251,7 +255,7 @@ xpack.notification.email.account: NOTE: If you have advanced security options enabled for your email account, you need to take additional steps to send email from {watcher}. For more - information, see <>. + information, see <>. You can check the watch history or the `status_index` to see that the action was performed. @@ -270,13 +274,13 @@ GET .watcher-history*/_search?pretty [float] [[health-delete]] -==== Delete the Watch +==== Delete the watch Since the `cluster_health_watch` is configured to run every 10 seconds, make sure you delete it when you're done experimenting. Otherwise, you'll spam yourself indefinitely. -To remove the watch, use the {ref}/watcher-api-delete-watch.html[DELETE watch API]: +To remove the watch, use the <>: [source,js] ------------------------------------------------------- diff --git a/x-pack/docs/en/watcher/example-watches/example-watch-meetupdata.asciidoc b/x-pack/docs/en/watcher/example-watches/example-watch-meetupdata.asciidoc index 082ff77f4a20c..6669bcd1d5c82 100644 --- a/x-pack/docs/en/watcher/example-watches/example-watch-meetupdata.asciidoc +++ b/x-pack/docs/en/watcher/example-watches/example-watch-meetupdata.asciidoc @@ -1,5 +1,5 @@ [[watching-meetup-data]] -=== Watching Event Data +=== Watching event data If you are indexing event data, such as log messages, network traffic, or a web feed, you can create a watch to email notifications when certain events occur. For example, if you index a feed of RSVPs for meetup events happening around the world, you can create a watch that alerts you to interesting events. @@ -188,7 +188,7 @@ To set up the watch: // NOTCONSOLE -- -NOTE: To enable Watcher to send emails, you must configure an email account in `elasticsearch.yml`. For more information, see <>. +NOTE: To enable Watcher to send emails, you must configure an email account in `elasticsearch.yml`. For more information, see <>. The complete watch looks like this: @@ -290,7 +290,7 @@ PUT _xpack/watcher/watch/meetup -------------------------------------------------- // CONSOLE -<1> The email body can include Mustache templates to reference data in the watch payload. By default,it will be <> to block dangerous content. +<1> The email body can include Mustache templates to reference data in the watch payload. By default,it will be <> to block dangerous content. <2> Replace the `from` address with the email address you configured in `elasticsearch.yml`. <3> Replace the `to` address with your email address to receive notifications. diff --git a/x-pack/docs/en/watcher/example-watches/watching-time-series-data.asciidoc b/x-pack/docs/en/watcher/example-watches/watching-time-series-data.asciidoc index c594687382b90..217cd857414f5 100644 --- a/x-pack/docs/en/watcher/example-watches/watching-time-series-data.asciidoc +++ b/x-pack/docs/en/watcher/example-watches/watching-time-series-data.asciidoc @@ -1,5 +1,5 @@ [[watching-time-series-data]] -=== Watching Time Series Data +=== Watching time series data If you are indexing time-series data such as logs, RSS feeds, or network traffic, you can use {watcher} to send notifications when certain events occur. @@ -151,7 +151,7 @@ you can then reference it by name in the watch condition. NOTE: To use the email action, you must configure at least one email account in `elasticsearch.yml`. If you configure multiple email accounts, you need to specify which one you want to send the email with. For more information, see -<>. +<>. The complete watch looks like this: diff --git a/x-pack/docs/en/watcher/getting-started.asciidoc b/x-pack/docs/en/watcher/getting-started.asciidoc index 41eb654bab30c..7f8a3e1e05da7 100644 --- a/x-pack/docs/en/watcher/getting-started.asciidoc +++ b/x-pack/docs/en/watcher/getting-started.asciidoc @@ -3,7 +3,10 @@ By default, when you install {es} and {kib}, {xpack} is installed and the {watcher} is enabled. You cannot use {watcher} with the free basic license, but -you can try all of the {xpack} features with a <>. +you can try all of the {xpack} features with a trial license. For more +information about Elastic license levels, see +https://www.elastic.co/subscriptions and +{stack-ov}/license-management.html[License management] [[watch-log-data]] To set up a watch to start sending alerts: @@ -16,14 +19,14 @@ condition is met. [float] [[log-add-input]] -=== Schedule the Watch and Define an Input +=== Schedule the watch and define an input -A watch {xpack-ref}/trigger-schedule.html[schedule] controls how often a watch is triggered. -The watch {xpack-ref}/input.html[input] gets the data that you want to evaluate. +A watch <> controls how often a watch is triggered. +The watch <> gets the data that you want to evaluate. To periodically search log data and load the results into the -watch, you could use an {xpack-ref}/trigger-schedule.html#schedule-interval[interval] schedule and a -{xpack-ref}/input-search.html[search] input. For example, the following Watch searches +watch, you could use an <> schedule and a +<> input. For example, the following Watch searches the `logs` index for errors every 10 seconds: [source,js] @@ -74,9 +77,9 @@ GET .watcher-history*/_search?pretty [float] [[log-add-condition]] -=== Add a Condition +=== Add a condition -A {xpack-ref}/condition.html[condition] evaluates the data you've loaded into the watch and +A <> 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. @@ -107,7 +110,7 @@ PUT _xpack/watcher/watch/log_error_watch } -------------------------------------------------- // CONSOLE -<1> The {xpack-ref}/condition-compare.html[compare] condition lets you easily compare against +<1> The <> 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 @@ -151,11 +154,11 @@ GET .watcher-history*/_search?pretty [float] [[log-take-action]] -=== Configure an 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 {xpack-ref}/actions.html[actions] define what to do when the watch condition +watch's <> 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. @@ -203,7 +206,7 @@ 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 {ref}/watcher-api-delete-watch.html[DELETE watch API]: +To remove the watch, use the <>: [source,js] -------------------------------------------------- @@ -214,7 +217,7 @@ DELETE _xpack/watcher/watch/log_error_watch [float] [[required-security-privileges]] -=== Required Security Privileges +=== Required security privileges To enable users to create and manipulate watches, assign them the `watcher_admin` security role. Watcher admins can also view watches, watch history, and triggered watches. @@ -225,11 +228,11 @@ allowed to execute read-only watch operations. [float] [[next-steps]] -=== Where to Go Next +=== Where to go next -* See {xpack-ref}/how-watcher-works.html[How {watcher} Works] for more information about the +* See <> for more information about the anatomy of a watch and the watch lifecycle. -* See {xpack-ref}/example-watches.html[Example Watches] for more examples of setting up +* See <> 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 diff --git a/x-pack/docs/en/watcher/gs-index.asciidoc b/x-pack/docs/en/watcher/gs-index.asciidoc index e799adec40a34..15de767244a1c 100644 --- a/x-pack/docs/en/watcher/gs-index.asciidoc +++ b/x-pack/docs/en/watcher/gs-index.asciidoc @@ -1,5 +1,5 @@ [[xpack-alerting]] -= Alerting on Cluster and Index Events += Alerting on cluster and index events [partintro] -- diff --git a/x-pack/docs/en/watcher/how-watcher-works.asciidoc b/x-pack/docs/en/watcher/how-watcher-works.asciidoc index 2bd19c1a41e02..6179cb7b03bc0 100644 --- a/x-pack/docs/en/watcher/how-watcher-works.asciidoc +++ b/x-pack/docs/en/watcher/how-watcher-works.asciidoc @@ -1,5 +1,5 @@ [[how-watcher-works]] -== How {watcher} Works +== How {watcher} works You <> to automatically perform an action when certain conditions are met. The conditions are generally based on data you've @@ -15,7 +15,7 @@ This topic describes the elements of a watch and how watches operate. [float] [[watch-definition]] -=== Watch Definition +=== Watch definition A watch consists of a _trigger_, _input_, _condition_, and _actions_. The actions define what needs to be done once the condition is met. In addition, you can @@ -43,7 +43,7 @@ Specify what happens when the watch condition is met. [[watch-definition-example]] For example, the following snippet shows a -{ref}/watcher-api-put-watch.html[Put Watch] request that defines a watch that +<> request that defines a watch that looks for log error events: [source,js] @@ -130,7 +130,7 @@ PUT _xpack/watcher/watch/log_errors [float] [[watch-execution]] -=== Watch Execution +=== Watch execution [[schedule-scheduler]] When you add a watch, {watcher} immediately registers its trigger with the @@ -198,7 +198,7 @@ image::images/watch-execution.jpg[align="center"] [float] [[watch-acknowledgment-throttling]] -=== Watch Acknowledgment and Throttling +=== Watch acknowledgment and throttling {watcher} supports both time-based and acknowledgment-based throttling. This enables you to prevent actions from being repeatedly executed for the same event. @@ -218,7 +218,7 @@ For more information, see <>. [float] [[watch-active-state]] -=== Watch Active State +=== Watch active state By default, when you add a watch it is immediately set to the _active_ state, registered with the appropriate trigger engine, and executed according @@ -228,13 +228,13 @@ You can also set a watch to the _inactive_ state. Inactive watches are not registered with a trigger engine and can never be triggered. To set a watch to the inactive state when you create it, set the -{ref}/watcher-api-put-watch.html[`active`] parameter to _inactive_. To +<> parameter to _inactive_. To deactivate an existing watch, use the -{ref}/watcher-api-deactivate-watch.html[Deactivate Watch API]. To reactivate an +<>. To reactivate an inactive watch, use the -{ref}/watcher-api-activate-watch.html[Activate Watch API]. +<>. -NOTE: You can use the {ref}/watcher-api-execute-watch.html[Execute Watch API] +NOTE: You can use the <> to force the execution of a watch even when it is inactive. Deactivating watches is useful in a variety of situations. For example, if you @@ -247,7 +247,7 @@ deleting it from the system. [float] [[scripts-templates]] -=== Scripts and Templates +=== Scripts and templates You can use scripts and templates when defining a watch. Scripts and templates can reference elements in the watch execution context, including the watch payload. @@ -258,13 +258,12 @@ placeholders in a template. <> and <>. Scripts and templates are compiled and cached by Elasticsearch to optimize recurring execution. Autoloading is also -supported. For more information, see {ref}/modules-scripting.html[Scripting] and -{ref}/modules-scripting-using.html[How to use scripts] in the Elasticsearch -Reference. +supported. For more information, see <> and +<>. [float] [[watch-execution-context]] -==== Watch Execution Context +==== Watch execution context The following snippet shows the basic structure of the _Watch Execution Context_: @@ -298,14 +297,14 @@ The following snippet shows the basic structure of the _Watch Execution Context_ [float] [[scripts]] -==== Using Scripts +==== Using scripts -You can use scripts to define <> and -<>. The default scripting language is -{ref}/modules-scripting-painless.html[Painless]. +You can use scripts to define <> and +<>. The default scripting language is +<>. NOTE: Starting with 5.0, Elasticsearch is shipped with the new - {ref}/modules-scripting-painless.html[Painless] scripting language. + <> scripting language. Painless was created and designed specifically for use in Elasticsearch. Beyond providing an extensive feature set, its biggest trait is that it's properly sandboxed and safe to use anywhere in the system (including in @@ -323,7 +322,7 @@ access its value via the `color` variable. [float] [[templates]] -==== Using Templates +==== Using templates You use templates to define dynamic content for a watch. At execution time, templates pull in data from the watch execution context. For example, you can use @@ -353,7 +352,7 @@ in sent emails: [float] [[inline-templates-scripts]] -===== Inline Templates and Scripts +===== Inline templates and scripts To define an inline template or script, you simply specify it directly in the value of a field. For example, the following snippet configures the subject of @@ -415,9 +414,9 @@ The formal object definition for a script would be: [float] [[stored-templates-scripts]] -===== Stored Templates and Scripts +===== Stored templates and scripts -If you {ref}/modules-scripting-using.html#modules-scripting-stored-scripts[store] +If you <> your templates and scripts, you can reference them by id. To reference a stored script or template, you use the formal object definition diff --git a/x-pack/docs/en/watcher/images/watcher-ui-edit-watch.png b/x-pack/docs/en/watcher/images/watcher-ui-edit-watch.png new file mode 100644 index 0000000000000..f6a3ab4354a21 Binary files /dev/null and b/x-pack/docs/en/watcher/images/watcher-ui-edit-watch.png differ diff --git a/x-pack/docs/en/watcher/index.asciidoc b/x-pack/docs/en/watcher/index.asciidoc index 2be3638971929..fe006fc3a23ff 100644 --- a/x-pack/docs/en/watcher/index.asciidoc +++ b/x-pack/docs/en/watcher/index.asciidoc @@ -97,3 +97,7 @@ include::managing-watches.asciidoc[] :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/watcher/example-watches.asciidoc include::example-watches.asciidoc[] + +include::troubleshooting.asciidoc[] + +include::limitations.asciidoc[] \ No newline at end of file diff --git a/x-pack/docs/en/watcher/input.asciidoc b/x-pack/docs/en/watcher/input.asciidoc index 6dee849c735f9..f248d69644e62 100644 --- a/x-pack/docs/en/watcher/input.asciidoc +++ b/x-pack/docs/en/watcher/input.asciidoc @@ -8,12 +8,12 @@ input. {watcher} supports four input types: -* <>: load static data into the execution context. -* <>: load the results of a search into the execution +* <>: load static data into the execution context. +* <>: load the results of a search into the execution context. -* <>: load the results of an HTTP request into the execution +* <>: load the results of an HTTP request into the execution context. -* <>: use a series of inputs to load data into the +* <>: use a series of inputs to load data into the execution context. NOTE: If you don't define an input for a watch, an empty payload is loaded diff --git a/x-pack/docs/en/watcher/input/chain.asciidoc b/x-pack/docs/en/watcher/input/chain.asciidoc index 9898880a9a760..c6151d3d0ed5b 100644 --- a/x-pack/docs/en/watcher/input/chain.asciidoc +++ b/x-pack/docs/en/watcher/input/chain.asciidoc @@ -1,5 +1,5 @@ [[input-chain]] -=== Chain Input +=== Chain input Use the `chain` input to load data from multiple sources into the watch execution context when the watch is triggered. The inputs in a chain @@ -44,12 +44,13 @@ path set by a `simple` input: arbitrary objects.) <2> Loads the `path` set by the `first` input. -==== Accessing Chained Input Data +==== Accessing chained input data To reference data loaded by a particular input, you use the input's name, `ctx.payload..`. -==== Transforming Chained Input Data +[[_transforming_chained_input_data]] +==== Transforming chained input data In certain use-cases the output of the first input should be used as input in a subsequent input. This requires you to do a transform, before you pass diff --git a/x-pack/docs/en/watcher/input/http.asciidoc b/x-pack/docs/en/watcher/input/http.asciidoc index 79d37d14a1bf4..d6fca8a7ad326 100644 --- a/x-pack/docs/en/watcher/input/http.asciidoc +++ b/x-pack/docs/en/watcher/input/http.asciidoc @@ -1,9 +1,9 @@ [[input-http]] -=== HTTP Input +=== HTTP input Use the `http` input to submit a request to an HTTP endpoint and load the response into the watch execution context when the watch is triggered. See -<> for all of the supported attributes. +<> for all of the supported attributes. With the `http` input, you can: @@ -13,15 +13,14 @@ With the `http` input, you can: need to search clusters that are running different Elasticsearch versions. * Query Elasticsearch APIs other than the search API. For example, you might want - to load data from the {ref}/cluster-nodes-stats.html[Nodes Stats], - {ref}/cluster-health.html[Cluster Health] or {ref}/cluster-state.html[Cluster - State] APIs. + to load data from the <>, + <> or <> APIs. * Query external web services. The `http` input enables you to load data from any service that exposes an HTTP endpoint. This provides a bridge between Elasticsearch clusters and other systems. -==== Querying External Elasticsearch Clusters +==== Querying external Elasticsearch clusters To query an external Elasticsearch cluster, you specify the cluster's `host` and `port` attributes and the index's search endpoint as the `path`. @@ -42,7 +41,7 @@ index: -------------------------------------------------- // NOTCONSOLE -You can use the full Elasticsearch {ref}/query-dsl.html[Query DSL] to perform +You can use the full Elasticsearch <> to perform more sophisticated searches. For example, the following `http` input retrieves all documents that contain `event` in the `category` field: @@ -66,8 +65,7 @@ all documents that contain `event` in the `category` field: To load the data from other Elasticsearch APIs, specify the API endpoint as the `path` attribute. Use the `params` attribute to specify query string parameters. For example, the following `http` input -calls the {ref}/cluster-stats.html[Cluster -Stats] API and enables the `human` attribute: +calls the <> API and enables the `human` attribute: [source,js] -------------------------------------------------- @@ -89,7 +87,7 @@ Stats] API and enables the `human` attribute: readable format. [[input-http-auth-basic-example]] -==== Calling External Web Services +==== Calling external web services You can use `http` input to get data from any external web service. The `http` input supports basic authentication. For example, the following input provides @@ -137,9 +135,9 @@ http://openweathermap.org/appid[OpenWeatherMap] service: -------------------------------------------------- // NOTCONSOLE -==== Using Templates +==== Using templates -The `http` input supports templating. You can use <> when +The `http` input supports templating. You can use <> when specifying the `path`, `body`, header values, and parameter values. For example, the following snippet uses templates to specify what index to query @@ -160,7 +158,7 @@ and restrict the results to documents added within the last five minutes: -------------------------------------------------- // NOTCONSOLE -==== Accessing the HTTP Response +==== Accessing the HTTP response If the response body is formatted in JSON or YAML, it is parsed and loaded into the execution context. If the response body is not formatted in JSON or YAML, it @@ -176,7 +174,7 @@ In addition all the headers from the response can be accessed using the [[http-input-attributes]] -==== HTTP Input Attributes +==== HTTP input attributes [cols=",^,^,", options="header"] |====== @@ -189,17 +187,17 @@ In addition all the headers from the response can be accessed using the | `request.port` | yes | - | The port the http service is listening on. | `request.path` | no | - | The URL path. The path can be static text or contain `mustache` - <>. URL query string parameters must be + <>. URL query string parameters must be specified via the `request.params` attribute. | `request.method` | no | get | The HTTP method. Supported values are: `head`, `get`, `post`, `put` and `delete`. | `request.headers` | no | - | The HTTP request headers. The header values can be static text - or include `mustache` <>. + or include `mustache` <>. | `request.params` | no | - | The URL query string parameters. The parameter values can be - static text or contain `mustache` <>. + static text or contain `mustache` <>. | `request.url` | no | - | Allows you to set `request.scheme`, `request.host`, `request.port` and `request.params` add once by specifying a real URL, like @@ -224,7 +222,7 @@ In addition all the headers from the response can be accessed using the | `request.body` | no | - | The HTTP request body. The body can be static text or include - `mustache` <>. + `mustache` <>. | `extract` | no | - | A array of JSON keys to extract from the input response and use as payload. In cases when an input generates a large diff --git a/x-pack/docs/en/watcher/input/search.asciidoc b/x-pack/docs/en/watcher/input/search.asciidoc index 7ce67bfc1dc2b..57f30ea26544c 100644 --- a/x-pack/docs/en/watcher/input/search.asciidoc +++ b/x-pack/docs/en/watcher/input/search.asciidoc @@ -1,15 +1,14 @@ [[input-search]] -=== Search Input +=== Search input Use the `search` input to load the results of an Elasticsearch search request into the execution context when the watch is triggered. See -<> for all of the -supported attributes. +<> for all of the supported attributes. In the search input's `request` object, you specify: * The indices you want to search -* The {ref}/search-request-search-type.html[search type] +* The <> * The search request body The search request body supports the full Elasticsearch Query DSL--it's the @@ -60,7 +59,7 @@ the following input loads the latest VIXZ quote from today's daily quotes index: -------------------------------------------------- // NOTCONSOLE -==== Extracting Specific Fields +==== Extracting specific fields You can specify which fields in the search response you want to load into the watch payload with the `extract` attribute. This is useful when a search @@ -82,9 +81,9 @@ watch payload: -------------------------------------------------- // NOTCONSOLE -==== Using Templates +==== Using templates -The `search` input supports {ref}/search-template.html[search templates]. For +The `search` input supports <>. For example, the following snippet references the indexed template called `my_template` and passes a value of 23 to fill in the template's `value` parameter: @@ -110,11 +109,11 @@ parameter: -------------------------------------------------- // NOTCONSOLE -==== Applying Conditions +==== Applying conditions -The `search` input is often used in conjunction with the <> condition. For example, the following snippet adds a condition to -check if the search returned more than five hits: +The `search` input is often used in conjunction with the +<> condition. For example, the following snippet adds +a condition to check if the search returned more than five hits: [source,js] -------------------------------------------------- @@ -137,7 +136,7 @@ check if the search returned more than five hits: -------------------------------------------------- // NOTCONSOLE -==== Accessing the Search Results +==== Accessing the search results Conditions, transforms, and actions can access the search results through the watch execution context. For example: @@ -157,7 +156,7 @@ watch execution context. For example: |====== | Name |Required | Default | Description -| `request.search_type` | no | `query_then_fetch` | The {ref}/search-request-search-type.html#search-request-search-type[type] +| `request.search_type` | no | `query_then_fetch` | The <> of search request to perform. Valid values are: `dfs_query_and_fetch`, `dfs_query_then_fetch`, `query_and_fetch`, and `query_then_fetch`. The Elasticsearch default is `query_then_fetch`. @@ -168,21 +167,21 @@ watch execution context. For example: | `request.types` | no | - | The document types to search for. If omitted, all document types are are searched, which is the default behaviour in Elasticsearch. -| `request.body` | no | - | The body of the request. The {ref}/search-request-body.html[request body] +| `request.body` | no | - | The body of the request. The <> follows the same structure you normally send in the body of a REST `_search` - request. The body can be static text or include `mustache` <>. + request. The body can be static text or include `mustache` <>. -| `request.template` | no | - | The body of the search template. See <> +| `request.template` | no | - | The body of the search template. See <> for more information. | `request.indices_options.expand_wildcards` | no | `open` | How to expand wildcards. Valid values are: `all`, `open`, `closed`, and `none` - See {ref}/multi-index.html#multi-index[`expand_wildcards`] for more information. + See <> for more information. | `request.indices_options.ignore_unavailable` | no | `true` | Whether the search should ignore unavailable indices. See - {ref}/multi-index.html#multi-index[`ignore_unavailable`] for more information. + <> for more information. | `request.indices_options.allow_no_indices` | no | `true` | Whether to allow a search where a wildcard indices expression results in no - concrete indices. See {ref}/multi-index.html#multi-index[allow_no_indices] + concrete indices. See <> for more information. | `extract` | no | - | A array of JSON keys to extract from the search response and load as the payload. diff --git a/x-pack/docs/en/watcher/input/simple.asciidoc b/x-pack/docs/en/watcher/input/simple.asciidoc index c756a4e5403e2..0cc9303dfa4a9 100644 --- a/x-pack/docs/en/watcher/input/simple.asciidoc +++ b/x-pack/docs/en/watcher/input/simple.asciidoc @@ -1,5 +1,5 @@ [[input-simple]] -=== Simple Input +=== Simple input Use the `simple` input to load static data into the execution context when the watch is triggered. This enables you to store the data diff --git a/x-pack/docs/en/watcher/java/ack-watch.asciidoc b/x-pack/docs/en/watcher/java/ack-watch.asciidoc index f24f0b89a0e1c..7cef48d6e3373 100644 --- a/x-pack/docs/en/watcher/java/ack-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/ack-watch.asciidoc @@ -1,13 +1,13 @@ [float] [[api-java-ack-watch]] -=== Ack Watch API +=== Ack watch API -<> a watch enables you to manually throttle +<> a watch enables you to manually throttle execution of the watch actions. The action's _acknowledgement state_ is stored in the `status.actions..ack.state` structure. The current status of the watch and the state of its actions are returned as part -of the <> response: +of the <> response: [source,java] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/java/activate-watch.asciidoc b/x-pack/docs/en/watcher/java/activate-watch.asciidoc index 63e88001a4be0..96ea3f5e23d8a 100644 --- a/x-pack/docs/en/watcher/java/activate-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/activate-watch.asciidoc @@ -1,12 +1,12 @@ [float] [[api-java-activate-watch]] -=== Activate Watch API +=== Activate watch API -A watch can be either <>. This API +A watch can be either <>. This API enables you to activate a currently inactive watch. The status of an inactive watch is returned with the watch definition -when you call the <>: +when you call the <>: [source,java] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/java/deactivate-watch.asciidoc b/x-pack/docs/en/watcher/java/deactivate-watch.asciidoc index 325f37bf32587..98c4220e68c88 100644 --- a/x-pack/docs/en/watcher/java/deactivate-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/deactivate-watch.asciidoc @@ -1,12 +1,12 @@ [float] [[api-java-deactivate-watch]] -=== Deactivate Watch API +=== Deactivate watch API -A watch can be either <>. This API +A watch can be either <>. This API enables you to deactivate a currently active watch. The status of an active watch is returned with the watch definition -when you call the <>: +when you call the <>: [source,java] -------------------------------------------------- diff --git a/x-pack/docs/en/watcher/java/delete-watch.asciidoc b/x-pack/docs/en/watcher/java/delete-watch.asciidoc index 4d37b910fd179..a019db933748c 100644 --- a/x-pack/docs/en/watcher/java/delete-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/delete-watch.asciidoc @@ -1,8 +1,8 @@ [float] [[api-java-delete-watch]] -=== Delete Watch API +=== Delete watch API -The DELETE watch API removes a watch (identified by its `id`) from {watcher}. +The delete watch API removes a watch (identified by its `id`) from {watcher}. Once removed, the document representing the watch in the `.watches` index is gone and it will never be executed again. diff --git a/x-pack/docs/en/watcher/java/execute-watch.asciidoc b/x-pack/docs/en/watcher/java/execute-watch.asciidoc index 34f2b8aa1e767..6379c09ed23d6 100644 --- a/x-pack/docs/en/watcher/java/execute-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/execute-watch.asciidoc @@ -1,6 +1,6 @@ [float] [[api-java-execute-watch]] -=== Execute Watch API +=== Execute watch API This API enables on-demand execution of a watch stored in the `.watches` index. It can be used to test a watch without executing all its actions or by ignoring diff --git a/x-pack/docs/en/watcher/java/get-watch.asciidoc b/x-pack/docs/en/watcher/java/get-watch.asciidoc index e4fcd86d85c85..f7a8c92fc20c2 100644 --- a/x-pack/docs/en/watcher/java/get-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/get-watch.asciidoc @@ -1,6 +1,6 @@ [float] [[api-java-get-watch]] -=== Get Watch API +=== Get watch API This API retrieves a watch by its id. diff --git a/x-pack/docs/en/watcher/java/put-watch.asciidoc b/x-pack/docs/en/watcher/java/put-watch.asciidoc index 1ac7b7f4db970..5552830477c15 100644 --- a/x-pack/docs/en/watcher/java/put-watch.asciidoc +++ b/x-pack/docs/en/watcher/java/put-watch.asciidoc @@ -1,8 +1,8 @@ [float] [[api-java-put-watch]] -=== PUT Watch API +=== Put watch API -The PUT watch API either registers a new watch in {watcher} or update an +The put watch API either registers a new watch in {watcher} or update an existing one. Once registered, a new document will be added to the `.watches` index, representing the watch, and the watch trigger will immediately be registered with the relevant trigger engine (typically the scheduler, for the diff --git a/x-pack/docs/en/watcher/limitations.asciidoc b/x-pack/docs/en/watcher/limitations.asciidoc new file mode 100644 index 0000000000000..f22c992327d31 --- /dev/null +++ b/x-pack/docs/en/watcher/limitations.asciidoc @@ -0,0 +1,32 @@ +[role="xpack"] +[[watcher-limitations]] +== Watcher limitations +++++ +Limitations +++++ + +[float] +=== Watches are not updated when file based scripts change + +When you refer to a file script in a watch, the watch itself is not updated +if you change the script on the filesystem. + +Currently, the only way to reload a file script in a watch is to delete +the watch and recreate it. + +[float] +=== Watcher UI + +When you create a new watch or edit an existing watch, if you navigate away +from the page without saving your changes they will be lost without warning. +Make sure to save your changes before leaving the page. + +image::images/watcher-ui-edit-watch.png[Editing a watch in Kibana] + +[float] +=== Security integration + +When the {security-features} are enabled, a watch stores information about what +the user who stored the watch is allowed to execute **at that time**. This means, +if those permissions change over time, the watch will still be able to execute +with the permissions that existed when the watch was created. diff --git a/x-pack/docs/en/watcher/managing-watches.asciidoc b/x-pack/docs/en/watcher/managing-watches.asciidoc index a155132d5e4b1..1d1069c257e7e 100644 --- a/x-pack/docs/en/watcher/managing-watches.asciidoc +++ b/x-pack/docs/en/watcher/managing-watches.asciidoc @@ -1,18 +1,18 @@ [[managing-watches]] -== Managing Watches +== Managing watches {watcher} provides as set of APIs you can use to manage your watches: -* Use the {ref}/watcher-api-put-watch.html[Put Watch API] to add or update watches -* Use the {ref}/watcher-api-get-watch.html[Get Watch API] to retrieve watches -* Use the {ref}/watcher-api-delete-watch.html[Delete Watch API] to delete watches -* Use the {ref}/watcher-api-activate-watch.html[Activate Watch API] to activate watches -* Use the {ref}/watcher-api-deactivate-watch.html[Deactivate Watch API] to deactivate watches -* Use the {ref}/watcher-api-ack-watch.html[Ack Watch API] to acknowledge watches +* Use the <> to add or update watches +* Use the <> to retrieve watches +* Use the <> to delete watches +* Use the <> to activate watches +* Use the <> to deactivate watches +* Use the <> to acknowledge watches [float] [[listing-watches]] -=== Listing Watches +=== Listing watches Currently there is not dedicated API for listing the stored watches. However, since {watcher} stores its watches in the `.watches` index, you can list them diff --git a/x-pack/docs/en/watcher/release-notes.asciidoc b/x-pack/docs/en/watcher/release-notes.asciidoc index 627c45829d3e2..a5678c0abc292 100644 --- a/x-pack/docs/en/watcher/release-notes.asciidoc +++ b/x-pack/docs/en/watcher/release-notes.asciidoc @@ -119,9 +119,9 @@ March 30, 2016 {ref}/watcher-api-execute-watch.html[Execute Watch API] .New Features -* Added <> -* Added support for adding <> - via HTTP requests and superceding and deprecating the usage of `attach_data` +* Added <> +* Added support for adding <> + via HTTP requests and superseding and deprecating the usage of `attach_data` in order to use this feature [float] @@ -157,7 +157,7 @@ December 17, 2015 November 24, 2015 .New Features -* Adds support for <> +* Adds support for <> .Enhancements * Adds support for Elasticsearch 2.1.0. @@ -204,13 +204,13 @@ October 28, 2015 use the following index name ``. .New Features -* Added new <> -* Added new <> -* Watches now have an <>. In addition, a new +* Added new <> +* Added new <> +* Watches now have an <>. In addition, a new API was added to {ref}/watcher-api-activate-watch.html[activate] /{ref}watcher-api-deactivate-watch.html[deactivate] registered watches. -* Added new <>, that can compare an array - of values in the <> +* Added new <>, that can compare an array + of values in the <> to a given value. .Enhancements @@ -273,40 +273,40 @@ June 25, 2015 June 19, 2015 .New Features -* Added <> support to the Execute API +* Added <> support to the Execute API .Enhancements -* Added execution context <> support. -* Email html body sanitization is now <>. +* Added execution context <> support. +* Email html body sanitization is now <>. * It is now possible to configure timeouts for http requests in - <> and <>. + <> and <>. [float] ==== 1.0.0-Beta2 June 10, 2015 .New Features -* <> are now applied at the action +* <> are now applied at the action level rather than the watch level. -* Added support for <> +* Added support for <> indexing to the index action. -* Added a queued watches metric that's accessible via the <>. +* Added a queued watches metric that's accessible via the <>. * Added a currently-executing watches metric that's accessible via the - <>. + <>. .Enhancements -* The <> result now includes the value of +* The <> result now includes the value of each field that was referenced in the comparison. -* The <> now supports a default trigger +* The <> now supports a default trigger event (**breaking change**). * The `watch_record` document structure in the `.watch_history-*` indices has changed significantly (**breaking change**). * A new internal index was introduced - `.triggered_watches` -* Added support for headers in the <> result - and the <> result. -* Add plain text response body support for the <>. +* Added support for headers in the <> result + and the <> result. +* Add plain text response body support for the <>. .Bug Fixes -* Disallow negative time value settings for <> -* Added support for separate keystore and truststore in <> - and <>. +* Disallow negative time value settings for <> +* Added support for separate keystore and truststore in <> + and <>. diff --git a/x-pack/docs/en/watcher/transform.asciidoc b/x-pack/docs/en/watcher/transform.asciidoc index 8241d7b0cb442..eb180969b1f46 100644 --- a/x-pack/docs/en/watcher/transform.asciidoc +++ b/x-pack/docs/en/watcher/transform.asciidoc @@ -1,10 +1,10 @@ [[transform]] == Transforms -A _Transform_ processes and changes the payload in the watch execution context +A _transform_ processes and changes the payload in the watch execution context to prepare it for the watch actions. {watcher} supports three types of -transforms: <>, -<> and <>. +transforms: <>, +<> and <>. NOTE: Transforms are optional. When none are defined, the actions have access to diff --git a/x-pack/docs/en/watcher/transform/chain.asciidoc b/x-pack/docs/en/watcher/transform/chain.asciidoc index 9ad27fe48ed81..b50d47e15562f 100644 --- a/x-pack/docs/en/watcher/transform/chain.asciidoc +++ b/x-pack/docs/en/watcher/transform/chain.asciidoc @@ -1,15 +1,15 @@ [[transform-chain]] -=== Chain Transform +=== Chain transform -A <> that executes an ordered list of configured transforms +A <> that executes an ordered list of configured transforms in a chain, where the output of one transform serves as the input of the next transform in the chain. The payload that is accepted by this transform serves as the input of the first transform in the chain and the output of the last transform in the chain is the output of the `chain` transform as a whole. You can use chain transforms to build more complex transforms out of the other -available transforms. For example, you can combine a <> -transform and a <> transform, as shown in the +available transforms. For example, you can combine a <> +transform and a <> transform, as shown in the following snippet: [source,js] diff --git a/x-pack/docs/en/watcher/transform/script.asciidoc b/x-pack/docs/en/watcher/transform/script.asciidoc index 9a1377eb5eab7..0a5dd1d579642 100644 --- a/x-pack/docs/en/watcher/transform/script.asciidoc +++ b/x-pack/docs/en/watcher/transform/script.asciidoc @@ -1,14 +1,14 @@ [[transform-script]] -=== Script Transform +=== Script transform -A <> that executes a script on the current payload in the +A <> that executes a script on the current payload in the watch execution context and replaces it with a newly generated one. The following snippet shows how a simple script transform can be defined on the watch level: TIP: The `script` transform is often useful when used in combination with the - <> transform, where the script can extract only + <> transform, where the script can extract only the significant data from a search result, and by that, keep the payload - minimal. This can be achieved with the <> + minimal. This can be achieved with the <> transform. @@ -32,13 +32,13 @@ NOTE: The executed script may either return a valid model that is the equivalent The `script` attribute may hold a string value in which case it will be treated as an inline script and the default elasticsearch script languages will be assumed -(as described in {ref}/modules-scripting.html#modules-scripting[here]). You can +(as described in <>). You can use the other scripting languages supported by Elasticsearch. For this, you need to set the `script` field to an object describing the script and its language. The following table lists the possible settings that can be configured: [[transform-script-settings]] -.Script Transform Settings +.Script transform settings [options="header"] |====== | Name |Required | Default | Description @@ -59,5 +59,5 @@ When using the object notation of the script, one (and only one) of `inline`, or `id` fields must be defined. NOTE: In addition to the provided `params`, the scripts also have access to the - <>. + <>. diff --git a/x-pack/docs/en/watcher/transform/search.asciidoc b/x-pack/docs/en/watcher/transform/search.asciidoc index 56f9304d986ce..4025d0fb45acb 100644 --- a/x-pack/docs/en/watcher/transform/search.asciidoc +++ b/x-pack/docs/en/watcher/transform/search.asciidoc @@ -1,7 +1,7 @@ [[transform-search]] -=== Search Transform +=== Search transform -A <> that executes a search on the cluster and replaces +A <> that executes a search on the cluster and replaces the current payload in the watch execution context with the returned search response. The following snippet shows how a simple search transform can be defined on the watch level: @@ -47,12 +47,12 @@ execute a search over all events indices, matching events with `error` priority: The following table lists all available settings for the search transform: [[transform-search-settings]] -.Search Transform Settings +.Search transform settings [cols=",^,,", options="header"] |====== | Name |Required | Default | Description -| `request.search_type` | no | query_then_fetch | The search {ref}/search-request-search-type.html[type]. +| `request.search_type` | no | query_then_fetch | The search <>. | `request.indices` | no | all indices | One or more indices to search on. @@ -61,25 +61,25 @@ The following table lists all available settings for the search transform: names) | `request.body` | no | `match_all` query | The body of the request. The - {ref}/search-request-body.html[request body] follows + <> follows the same structure you normally send in the body of a REST `_search` request. The body can be static text - or include `mustache` <>. + or include `mustache` <>. | `request.indices_options.expand_wildcards` | no | `open` | Determines how to expand indices wildcards. Can be one of `open`, `closed`, `none` or `all` - (see {ref}/multi-index.html[multi-index support]) + (see <>) | `request.indices_options.ignore_unavailable` | no | `true` | A boolean value that determines whether the search should leniently ignore unavailable indices - (see {ref}/multi-index.html[multi-index support]) + (see <>) | `request.indices_options.allow_no_indices` | no | `true` | A boolean value that determines whether the search should leniently return no results when no indices - are resolved (see {ref}/multi-index.html[multi-index support]) + are resolved (see <>) | `request.template` | no | - | The body of the search template. See - <> for more information. + <> for more information. | `timeout` | no | 30s | The timeout for waiting for the search api call to return. If no response is returned within this time, @@ -88,11 +88,11 @@ The following table lists all available settings for the search transform: |====== [[transform-search-template]] -==== Template Support +==== Template support The search transform support mustache <>. This can either be as part of the body definition, or alternatively, point to an existing -template (either defined in a file or {ref}/search-template.html#pre-registered-templates[registered] +template (either defined in a file or <> as a script in Elasticsearch). For example, the following snippet shows a search that refers to the scheduled @@ -134,7 +134,7 @@ time of the watch: // NOTCONSOLE The model of the template is a union between the provided `template.params` -settings and the <>. +settings and the <>. The following is an example of using templates that refer to provided parameters: diff --git a/x-pack/docs/en/watcher/trigger.asciidoc b/x-pack/docs/en/watcher/trigger.asciidoc index af830e829a45e..1a7aca77f68cd 100644 --- a/x-pack/docs/en/watcher/trigger.asciidoc +++ b/x-pack/docs/en/watcher/trigger.asciidoc @@ -7,7 +7,7 @@ appropriate _Trigger Engine_. The trigger engine is responsible for evaluating the trigger and triggering the watch when needed. {watcher} is designed to support different types of triggers, but only time-based -<> triggers are currently available. +<> triggers are currently available. :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/watcher/trigger/schedule.asciidoc include::trigger/schedule.asciidoc[] diff --git a/x-pack/docs/en/watcher/trigger/schedule.asciidoc b/x-pack/docs/en/watcher/trigger/schedule.asciidoc index abbc3f5cfe8e5..7300756803321 100644 --- a/x-pack/docs/en/watcher/trigger/schedule.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule.asciidoc @@ -1,7 +1,7 @@ [[trigger-schedule]] -=== Schedule Trigger +=== Schedule trigger -Schedule <> define when the watch execution should start based +Schedule <> define when the watch execution should start based on date and time. All times are specified in UTC time. {watcher} uses the system clock to determine the current time. To ensure schedules @@ -14,7 +14,7 @@ that's more frequent than the throttle period, the throttle period overrides the schedule. For example, if you set the throttle period to one minute (60000 ms) and set the schedule to every 10 seconds, the watch is executed no more than once per minute. For more information about throttling, see -<>. +<>. {watcher} provides several types of schedule triggers: diff --git a/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc index 57a6ebdfd92ef..d19a6fda500a8 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc @@ -1,7 +1,7 @@ [[schedule-cron]] ==== `cron` Schedule -A <> trigger that enables you to use a +A <> trigger that enables you to use a https://en.wikipedia.org/wiki/Cron[cron] style expression to specify when you want the scheduler to start the watch execution. {watcher} uses the cron parser from the http://www.quartz-scheduler.org[Quartz Job Scheduler]. For more @@ -12,10 +12,10 @@ WARNING: While `cron` triggers are super powerful, we recommend using one of the other schedule types if you can, as they are much more straightforward to configure. If you use `cron`, construct your `cron` expressions with care to be sure you are actually setting the schedule - you want. You can use the <> tool to validate + you want. You can use the <> tool to validate your cron expressions and see what the resulting trigger times will be. -===== Cron Expressions +===== Cron expressions A cron expression is a string of the following form: @@ -28,7 +28,7 @@ All elements are required except for `year`. <> shows the valid values for each element in a cron expression. [[schedule-cron-elements]] -.Cron Expression Elements +.Cron expression elements [cols=",^,,", options="header"] |====== | Name | Required | Valid Values | Valid Special Characters @@ -49,7 +49,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or `day_of_month`. Explicitly specifying both values is not supported. [[schedule-cron-special-characters]] -.Cron Special Characters +.Cron special characters [options="header"] |====== | Special Character | Description @@ -116,7 +116,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or |====== -.Setting Daily Triggers +.Setting daily triggers [options="header"] |====== | Cron Expression | Description @@ -124,7 +124,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or | `0 5 9 * * ? 2015` | Trigger at 9:05 AM every day during the year 2015. |====== -.Restricting Triggers to a Range of Days or Times +.Restricting triggers to a range of days or times [options="header"] |====== | Cron Expression | Description @@ -133,7 +133,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or at 9:05 AM every day. |====== -.Setting Interval Triggers +.Setting interval triggers [options="header"] |====== | Cron Expression | Description @@ -143,7 +143,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or on the first day of the month. |====== -.Setting Schedules that Trigger on a Particular Day +.Setting schedules that trigger on a particular day [options="header"] |====== | Cron Expression | Description @@ -156,7 +156,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or | `0 5 9 ? * 6#1` | Trigger at 9:05 AM on the first Friday of every month. |====== -.Setting Triggers Using Last +.Setting triggers using last [options="header"] |====== | Cron Expression | Description @@ -166,7 +166,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or |====== -===== Configuring a Cron Schedule +===== Configuring a cron schedule To configure a `cron` schedule, you simply specify the cron expression as a string value. For example, the following snippet configures a `cron` schedule @@ -186,7 +186,7 @@ that triggers every day at noon: -------------------------------------------------- // NOTCONSOLE -===== Configuring a Multiple Times Cron Schedule +===== Configuring a multiple times cron schedule To configure a `cron` schedule that triggers multiple times, you can specify an array of cron expressions. For example, the following `cron` diff --git a/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc index e729335d59b29..c380edf066860 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc @@ -1,18 +1,18 @@ [[schedule-daily]] -==== Daily Schedule +==== Daily schedule -A <> that triggers at a particular time +A <> that triggers at a particular time every day. To use the `daily` schedule, you specify the time of day (or times) when you want the scheduler to start the watch execution with the `at` attribute. Times are specified in the form `HH:mm` on a 24-hour clock. You can also use the reserved values `midnight` and `noon` for `00:00` and `12:00`, and -<>. +<>. NOTE: If you don't specify the `at` attribute for a `daily` schedule, it defaults to firing once daily at midnight, `00:00`. -===== Configuring a Daily Schedule +===== Configuring a daily schedule To configure a once a day schedule, you specify a single time with the `at` attribute. For example, the following `daily` schedule triggers once every @@ -30,7 +30,7 @@ day at 5:00 PM: -------------------------------------------------- // NOTCONSOLE -===== Configuring a Multiple Times Daily Schedule +===== Configuring a multiple times daily schedule To configure a `daily` schedule that triggers at multiple times during the day, you specify an array of times. For example, the following `daily` schedule @@ -49,7 +49,7 @@ triggers at `00:00`, `12:00`, and `17:00` every day. // NOTCONSOLE [[specifying-times-using-objects]] -===== Specifying Times Using Objects +===== Specifying times using objects In addition to using the `HH:mm` string syntax to specify times, you can specify a time as an object that has `hour` and `minute` attributes. diff --git a/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc index 9ec750eebcd2b..9b5a09b0fff5d 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc @@ -1,7 +1,7 @@ [[schedule-hourly]] -==== Hourly Schedule +==== Hourly schedule -A <> that triggers at a particular minute every +A <> that triggers at a particular minute every hour of the day. To use the `hourly` schedule, you specify the minute (or minutes) when you want the scheduler to start the watch execution with the `minute` attribute. @@ -10,7 +10,7 @@ NOTE: If you don't specify the `minute` attribute for an `hourly` schedule, it defaults to `0` and the schedule triggers on the hour every hour--`12:00`, `13:00`, `14:00`, and so on. -===== Configuring a Once an Hour Schedule +===== Configuring a once an hour schedule To configure a once an hour schedule, you specify a single time with the `minute` attribute. @@ -30,7 +30,7 @@ For example, the following `hourly` schedule triggers at minute 30 every hour-- -------------------------------------------------- // NOTCONSOLE -===== Configuring a Multiple Times Hourly Schedule +===== Configuring a multiple times hourly schedule To configure an `hourly` schedule that triggers at multiple times during the hour, you specify an array of minutes. For example, the following schedule diff --git a/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc index e534181ec0c2f..1b86d166455c2 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc @@ -1,7 +1,7 @@ [[schedule-interval]] -==== Interval Schedule +==== Interval schedule -A <> that triggers at a fixed time interval. The +A <> that triggers at a fixed time interval. The interval can be set in seconds, minutes, hours, days, or weeks: * `"Xs"` - trigger every `X` seconds. For example, `"30s"` means every 30 seconds. @@ -16,7 +16,7 @@ NOTE: The interval value differs from the standard _time value_ used in Elasticsearch. You cannot configure intervals in milliseconds or nanoseconds. -===== Configuring an Interval Schedule +===== Configuring an interval schedule To configure an `interval` schedule, you specify a string value that represents the interval. If you omit the unit of time (`s`,`m`, `h`, `d`, or `w`), it diff --git a/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc index d2cfe409992a7..97e5e63da3d0c 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc @@ -1,7 +1,7 @@ [[schedule-monthly]] -==== Monthly Schedule +==== Monthly schedule -A <> that triggers at a specific day and time +A <> that triggers at a specific day and time every month. To use the `monthly` schedule, you specify the day of the month and time (or days and times) when you want the scheduler to start the watch execution with the `on` and `at` attributes. @@ -10,7 +10,7 @@ You specify the day of month as a numeric value between `1` and `31` (inclusive) Times are specified in the form `HH:mm` on a 24-hour clock. You can also use the reserved values `midnight` and `noon` for `00:00` and `12:00`. -===== Configuring a Monthly Schedule +===== Configuring a monthly schedule To configure a once a month schedule, you specify a single day and time with the `on` and `at` attributes. For example, the following `monthly` schedule triggers @@ -31,7 +31,7 @@ on the 10th of each month at noon: NOTE: You can also specify the day and time with the `day` and `time` attributes, they are interchangeable with `on` and `at`. -===== Configuring a Multiple Times Monthly Schedule +===== Configuring a multiple times monthly schedule To configure a `monthly` schedule that triggers multiple times a month, you can specify an array of day and time values. For example, the following `monthly` diff --git a/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc index d6a403cb125c6..283089a8d5398 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc @@ -1,7 +1,7 @@ [[schedule-weekly]] -==== Weekly Schedule +==== Weekly schedule -A <> that triggers at a specific day and time +A <> that triggers at a specific day and time every week. To use the `weekly` schedule, you specify the day and time (or days and times) when you want the scheduler to start the watch execution with the `on` and `at` attributes. @@ -16,7 +16,7 @@ being the first day of the week): Times are specified in the form `HH:mm` on a 24-hour clock. You can also use the reserved values `midnight` and `noon` for `00:00` and `12:00`. -===== Configuring a Weekly Schedule +===== Configuring a weekly schedule To configure a once a week schedule, you specify the day with the `on` attribute and the time with the `at` attribute. For example, the following `weekly` schedule @@ -37,7 +37,7 @@ triggers once a week on Friday at 5:00 PM: NOTE: You can also specify the day and time with the `day` and `time` attributes, they are interchangeable with `on` and `at`. -===== Configuring a Multiple Times Weekly Schedule +===== Configuring a multiple times weekly schedule To configure a `weekly` schedule that triggers multiple times a week, you can specify an array of day and time values. For example, the following `weekly` diff --git a/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc index d11cc5d072787..c6240e1bb958c 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc @@ -1,7 +1,7 @@ [[schedule-yearly]] -==== Yearly Schedule +==== Yearly schedule -A <> that triggers at a specific day and time +A <> that triggers at a specific day and time every year. To use the `yearly` schedule, you specify the month, day, and time (or months, days, and times) when you want the scheduler to start the watch execution with the `in`, `on`, and `at` attributes. @@ -20,7 +20,7 @@ You specify the day of month as a numeric value between `1` and `31` (inclusive) The Times are specified in the form `HH:mm` on a 24-hour clock. You can also use the reserved values `midnight` and `noon` for `00:00` and `12:00`. -===== Configuring a Yearly Schedule +===== Configuring a yearly schedule To configure a once a year schedule, you specify the month with the `in` attribute, the day with the `on` attribute, and the time with the `at` attribute. For @@ -42,7 +42,7 @@ example, the following `yearly` schedule triggers once a year at noon on January NOTE: You can also specify the month, day, and time with the `month`, `day`, and `time` attributes, they are interchangeable with `in`, `on`, and `at`. -===== Configuring a Multiple Times Yearly Schedule +===== Configuring a multiple times yearly schedule To configure a `yearly` schedule that triggers multiple times a year, you can specify an array of month, day, and time values. For example, the following diff --git a/x-pack/docs/en/watcher/troubleshooting.asciidoc b/x-pack/docs/en/watcher/troubleshooting.asciidoc new file mode 100644 index 0000000000000..5ddc108e6a2fc --- /dev/null +++ b/x-pack/docs/en/watcher/troubleshooting.asciidoc @@ -0,0 +1,66 @@ +[role="xpack"] +[testenv="gold"] +[[watcher-troubleshooting]] +== Troubleshooting {watcher} +++++ +Troubleshooting +++++ + +[float] +=== Dynamic mapping error when trying to add a watch + +If you get the _Dynamic Mapping is Disabled_ error when you try to add a watch, +verify that the index mappings for the `.watches` index are available. You can +do that by submitting the following request: + +[source,js] +-------------------------------------------------- +GET .watches/_mapping +-------------------------------------------------- +// CONSOLE +// TEST[setup:my_active_watch] + +If the index mappings are missing, follow these steps to restore the correct +mappings: + +. Stop the Elasticsearch node. +. Add `xpack.watcher.index.rest.direct_access : true` to `elasticsearch.yml`. +. Restart the Elasticsearch node. +. Delete the `.watches` index: ++ +-- +[source,js] +-------------------------------------------------- +DELETE .watches +-------------------------------------------------- +// CONSOLE +// TEST[skip:index deletion] +-- +. Disable direct access to the `.watches` index: +.. Stop the Elasticsearch node. +.. Remove `xpack.watcher.index.rest.direct_access : true` from `elasticsearch.yml`. +.. Restart the Elasticsearch node. + +[float] +=== Unable to send email + +If you get an authentication error indicating that you need to continue the +sign-in process from a web browser when Watcher attempts to send email, you need +to configure Gmail to +https://support.google.com/accounts/answer/6010255?hl=en[Allow Less Secure Apps to access your account]. + +If you have two-step verification enabled for your email account, you must +generate and use an App Specific password to send email from {watcher}. For more +information, see: + +- Gmail: https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords] +- Outlook.com: http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification[App passwords and two-step verification] + +[float] +=== {watcher} not responsive + +Keep in mind that there's no built-in validation of scripts that you add to a +watch. Buggy or deliberately malicious scripts can negatively impact {watcher} +performance. For example, if you add multiple watches with buggy script +conditions in a short period of time, {watcher} might be temporarily unable to +process watches until the bad watches time out.