From 0c3ee0b15c8c66e1e8ef13642ae8b22afe0c3a7a Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 30 Sep 2019 10:18:50 -0700 Subject: [PATCH] [DOCS] Moves Watcher content into Elasticsearch book (#47147) (#47255) Co-Authored-By: James Rodewig --- .../high-level/watcher/ack-watch.asciidoc | 2 +- docs/painless/painless-contexts.asciidoc | 4 +- ...ainless-watcher-condition-context.asciidoc | 2 +- ...ainless-watcher-context-variables.asciidoc | 2 +- ...ainless-watcher-transform-context.asciidoc | 2 +- docs/reference/commands/syskeygen.asciidoc | 3 +- docs/reference/ilm/apis/slm-api.asciidoc | 2 +- .../ilm/getting-started-slm.asciidoc | 2 +- docs/reference/index.asciidoc | 2 + .../settings/notification-settings.asciidoc | 34 ++++----- .../setup/bootstrap-checks-xes.asciidoc | 3 +- .../en/rest-api/watcher/ack-watch.asciidoc | 2 +- .../rest-api/watcher/activate-watch.asciidoc | 3 +- .../watcher/deactivate-watch.asciidoc | 3 +- .../rest-api/watcher/execute-watch.asciidoc | 9 ++- .../en/rest-api/watcher/put-watch.asciidoc | 14 ++-- x-pack/docs/en/watcher/actions.asciidoc | 17 +++-- x-pack/docs/en/watcher/actions/email.asciidoc | 39 +++++------ x-pack/docs/en/watcher/actions/index.asciidoc | 12 ++-- x-pack/docs/en/watcher/actions/jira.asciidoc | 12 ++-- .../docs/en/watcher/actions/logging.asciidoc | 4 +- .../en/watcher/actions/pagerduty.asciidoc | 22 +++--- x-pack/docs/en/watcher/actions/slack.asciidoc | 18 ++--- .../docs/en/watcher/actions/webhook.asciidoc | 26 +++---- x-pack/docs/en/watcher/condition.asciidoc | 16 ++--- .../docs/en/watcher/condition/always.asciidoc | 6 +- .../watcher/condition/array-compare.asciidoc | 20 +++--- .../en/watcher/condition/compare.asciidoc | 12 ++-- .../docs/en/watcher/condition/never.asciidoc | 4 +- .../docs/en/watcher/condition/script.asciidoc | 34 ++++----- .../en/watcher/customizing-watches.asciidoc | 69 ++++++++++--------- .../docs/en/watcher/encrypting-data.asciidoc | 11 ++- .../docs/en/watcher/example-watches.asciidoc | 8 +-- .../example-watch-clusterstatus.asciidoc | 40 ++++++----- .../example-watch-meetupdata.asciidoc | 6 +- .../watching-time-series-data.asciidoc | 4 +- .../docs/en/watcher/getting-started.asciidoc | 33 ++++----- x-pack/docs/en/watcher/gs-index.asciidoc | 2 +- .../en/watcher/how-watcher-works.asciidoc | 47 +++++++------ x-pack/docs/en/watcher/input.asciidoc | 8 +-- x-pack/docs/en/watcher/input/chain.asciidoc | 6 +- x-pack/docs/en/watcher/input/http.asciidoc | 34 +++++---- x-pack/docs/en/watcher/input/search.asciidoc | 35 +++++----- x-pack/docs/en/watcher/input/simple.asciidoc | 2 +- .../docs/en/watcher/java/ack-watch.asciidoc | 6 +- .../en/watcher/java/activate-watch.asciidoc | 6 +- .../en/watcher/java/deactivate-watch.asciidoc | 6 +- .../en/watcher/java/delete-watch.asciidoc | 4 +- .../en/watcher/java/execute-watch.asciidoc | 2 +- .../docs/en/watcher/java/get-watch.asciidoc | 2 +- .../docs/en/watcher/java/put-watch.asciidoc | 4 +- .../docs/en/watcher/managing-watches.asciidoc | 16 ++--- x-pack/docs/en/watcher/release-notes.asciidoc | 48 ++++++------- x-pack/docs/en/watcher/transform.asciidoc | 6 +- .../docs/en/watcher/transform/chain.asciidoc | 8 +-- .../docs/en/watcher/transform/script.asciidoc | 14 ++-- .../docs/en/watcher/transform/search.asciidoc | 26 +++---- x-pack/docs/en/watcher/trigger.asciidoc | 2 +- .../docs/en/watcher/trigger/schedule.asciidoc | 6 +- .../en/watcher/trigger/schedule/cron.asciidoc | 26 +++---- .../watcher/trigger/schedule/daily.asciidoc | 12 ++-- .../watcher/trigger/schedule/hourly.asciidoc | 8 +-- .../trigger/schedule/interval.asciidoc | 6 +- .../watcher/trigger/schedule/monthly.asciidoc | 8 +-- .../watcher/trigger/schedule/weekly.asciidoc | 8 +-- .../watcher/trigger/schedule/yearly.asciidoc | 8 +-- 66 files changed, 431 insertions(+), 437 deletions(-) diff --git a/docs/java-rest/high-level/watcher/ack-watch.asciidoc b/docs/java-rest/high-level/watcher/ack-watch.asciidoc index 7bd28fa3a59..7dfc3faad8e 100644 --- a/docs/java-rest/high-level/watcher/ack-watch.asciidoc +++ b/docs/java-rest/high-level/watcher/ack-watch.asciidoc @@ -11,7 +11,7 @@ [id="{upid}-{api}-request"] ==== Execution -{stack-ov}/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 3bb3fc7d97e..10a4369b80a 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/index.asciidoc[] diff --git a/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc index 01ca156be14..945c47646cc 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[watch condition] +Use a Painless script as a {ref}/condition-script.html[watch condition] that determines whether to execute a watch or a particular action within a watch. Condition scripts return a Boolean value to indicate the status of the condition. diff --git a/docs/painless/painless-contexts/painless-watcher-context-variables.asciidoc b/docs/painless/painless-contexts/painless-watcher-context-variables.asciidoc index addfd11cab9..71a00711091 100644 --- a/docs/painless/painless-contexts/painless-watcher-context-variables.asciidoc +++ b/docs/painless/painless-contexts/painless-watcher-context-variables.asciidoc @@ -29,7 +29,7 @@ The following variables are available in all watcher contexts. `ctx['payload']` (`Map`, read-only):: The accessible watch data based upon the - {xpack-ref}/input.html[watch input]. + {ref}/input.html[watch input]. *API* diff --git a/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc index d96ab5f1521..9d71a5f2335 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 as a {xpack-ref}/transform-script.html[watch transform] +Use a Painless script as a {ref}/transform-script.html[watch transform] to transform a payload into a new payload for further use in the watch. Transform scripts return an Object value of the new payload. diff --git a/docs/reference/commands/syskeygen.asciidoc b/docs/reference/commands/syskeygen.asciidoc index 3ae7456448d..06d8330a122 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/ilm/apis/slm-api.asciidoc b/docs/reference/ilm/apis/slm-api.asciidoc index 013225f9696..c9db692b2e8 100644 --- a/docs/reference/ilm/apis/slm-api.asciidoc +++ b/docs/reference/ilm/apis/slm-api.asciidoc @@ -80,7 +80,7 @@ The top-level keys that the policy supports are described below: | `schedule` | A periodic or absolute time schedule. Supports all values supported by the cron scheduler: - {xpack-ref}/trigger-schedule.html#schedule-cron[Cron scheduler configuration] + <> | `name` | A name automatically given to each snapshot performed by this policy. Supports the same <> supported in index diff --git a/docs/reference/ilm/getting-started-slm.asciidoc b/docs/reference/ilm/getting-started-slm.asciidoc index e6f7dff2749..c41d4da4092 100644 --- a/docs/reference/ilm/getting-started-slm.asciidoc +++ b/docs/reference/ilm/getting-started-slm.asciidoc @@ -97,7 +97,7 @@ PUT /_slm/policy/nightly-snapshots -------------------------------------------------- // TEST[continued] <1> when the snapshot should be taken, using - {xpack-ref}/trigger-schedule.html#schedule-cron[Cron syntax], in this + <>, in this case at 1:30AM each day <2> whe name each snapshot should be given, using <> to include the current date in the name diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 1967c043146..563993f2133 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -56,6 +56,8 @@ include::high-availability.asciidoc[] include::security/index.asciidoc[] +include::{xes-repo-dir}/watcher/index.asciidoc[] + include::commands/index.asciidoc[] include::how-to.asciidoc[] diff --git a/docs/reference/settings/notification-settings.asciidoc b/docs/reference/settings/notification-settings.asciidoc index 97e51131606..9640c9df4df 100644 --- a/docs/reference/settings/notification-settings.asciidoc +++ b/docs/reference/settings/notification-settings.asciidoc @@ -27,14 +27,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 -{xpack-ref}/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 -{xpack-ref}/encrypting-data.html[Encrypting sensitive data in {watcher}]. +required. For more information, see <>. `xpack.watcher.history.cleaner_service.enabled`:: added:[6.3.0,Default changed to `true`.] @@ -88,7 +86,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 {xpack-ref}/actions-email.html#configuring-email-actions[Configuring Email]. +via email, see <>. `xpack.notification.email.account`:: Specifies account information for sending notifications via email. You @@ -98,14 +96,15 @@ can specify the following email account attributes: [[email-account-attributes]] `profile` (<>);; - The {xpack-ref}/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 {xpack-ref}/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 @@ -166,9 +165,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 {xpack-ref}/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]] @@ -229,7 +228,7 @@ include::ssl-settings.asciidoc[] ==== Slack Notification Settings You can configure the following Slack notification settings in `elasticsearch.yml`. For more information about sending notifications -via Slack, see {xpack-ref}/actions-slack.html#configuring-slack-actions[Configuring Slack]. +via Slack, see <>. `xpack.notification.slack` :: Specifies account information for sending notifications @@ -270,7 +269,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 {xpack-ref}/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 @@ -290,7 +289,7 @@ issues in Jira. You can specify the following Jira account attributes: `issue_defaults`;; Default fields values for the issue created in Jira. See - {xpack-ref}/actions-jira.html#jira-action-attributes[Jira Action Attributes] for more information. + <> for more information. Optional. -- @@ -299,7 +298,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 {xpack-ref}/actions-pagerduty.html#configuring-pagerduty-actions[Configuring PagerDuty]. +via PagerDuty, see <>. [[pagerduty-account-attributes]] @@ -318,8 +317,9 @@ PagerDuty API key] to use to access PagerDuty. Required. -- + `event_defaults`;; -Default values for {xpack-ref}/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 37c90e9f4d9..4cf55a00723 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 1ca9b101e83..33d128c166a 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. [[watcher-api-ack-watch-request]] 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 cc1386d0251..7151e42a103 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. [[watcher-api-activate-watch-request]] 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 f492090420a..7753adac2b9 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. [[watcher-api-deactivate-watch-request]] 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 112c39386fd..d4edff7bf35 100644 --- a/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc @@ -65,14 +65,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 @@ -81,8 +81,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. |====== @@ -99,7 +98,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 bbfcf234923..63c0ad2b9b6 100644 --- a/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc +++ b/x-pack/docs/en/rest-api/watcher/put-watch.asciidoc @@ -32,8 +32,8 @@ IMPORTANT: You must use {kib} or this API to create a watch. Do not put a watch privileges on the `.watches` index. When adding a watch you can also define its initial -{stack-ov}/how-watcher-works.html#watch-active-state[active state]. You do that -by setting the `active` parameter. +<>. You do that by setting the `active` +parameter. [[watcher-api-put-watch-security]] ===== Security integration @@ -65,16 +65,16 @@ A watch has the following fields: |====== | Name | Description -| `trigger` | The {stack-ov}/trigger.html[trigger] that defines when +| `trigger` | The <> that defines when the watch should run. -| `input` | The {stack-ov}/input.html[input] that defines the input +| `input` | The <> that defines the input that loads the data for the watch. -| `condition` | The {stack-ov}/condition.html[condition] that defines if +| `condition` | The <> that defines if the actions should be run. -| `actions` | The list of {stack-ov}/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. @@ -163,7 +163,7 @@ PUT _watcher/watch/my-watch -------------------------------------------------- When you add a watch you can also define its initial -{stack-ov}/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 6697fe59083..e140e622d30 100644 --- a/x-pack/docs/en/watcher/actions.asciidoc +++ b/x-pack/docs/en/watcher/actions.asciidoc @@ -3,7 +3,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. @@ -16,13 +16,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 @@ -94,7 +94,7 @@ PUT _watcher/watch/error_logs_alert <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,console] ---------------------------------------------------------------------- diff --git a/x-pack/docs/en/watcher/actions/email.asciidoc b/x-pack/docs/en/watcher/actions/email.asciidoc index c249aa85572..adda53b810d 100644 --- a/x-pack/docs/en/watcher/actions/email.asciidoc +++ b/x-pack/docs/en/watcher/actions/email.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[actions-email]] -=== Email Action +=== Email action Use the `email` action to send email notifications. To send email, you must <> in @@ -16,7 +16,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. @@ -48,7 +48,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 @@ -152,20 +152,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}/user/reporting/watch-example.asciidoc[] - -include::{kib-repo-dir}/user/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"] |====== @@ -250,7 +245,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 @@ -279,14 +274,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] -------------------------------------------------- @@ -301,7 +296,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: @@ -339,7 +334,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: @@ -375,7 +370,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: @@ -412,7 +407,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: @@ -447,7 +442,7 @@ bin/elasticsearch-keystore add xpack.notification.email.account.exchange_account [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/index.asciidoc b/x-pack/docs/en/watcher/actions/index.asciidoc index faaf80365aa..14a755712bb 100644 --- a/x-pack/docs/en/watcher/actions/index.asciidoc +++ b/x-pack/docs/en/watcher/actions/index.asciidoc @@ -1,11 +1,11 @@ [role="xpack"] [[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,14 +24,14 @@ 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> 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"] |====== @@ -56,7 +56,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 514618d5b57..e2c2a4824a1 100644 --- a/x-pack/docs/en/watcher/actions/jira.asciidoc +++ b/x-pack/docs/en/watcher/actions/jira.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [[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. @@ -49,7 +49,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 @@ -100,7 +100,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`. @@ -141,7 +141,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] -------------------------------------------------- @@ -159,7 +159,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 e1b6d31d86d..a279c83c208 100644 --- a/x-pack/docs/en/watcher/actions/logging.asciidoc +++ b/x-pack/docs/en/watcher/actions/logging.asciidoc @@ -8,7 +8,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. @@ -34,7 +34,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 2d9d091882f..47fd282c40d 100644 --- a/x-pack/docs/en/watcher/actions/pagerduty.asciidoc +++ b/x-pack/docs/en/watcher/actions/pagerduty.asciidoc @@ -1,13 +1,13 @@ [role="xpack"] [[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. @@ -31,7 +31,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. @@ -65,7 +65,7 @@ payload as well as an array of contexts to the action. [[pagerduty-action-attributes]] -==== Pagerduty Action Attributes +==== Pagerduty action attributes [cols=",^,", options="header"] |====== @@ -76,7 +76,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 @@ -115,7 +115,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 @@ -129,7 +129,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`. @@ -149,7 +149,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 deprecated[7.0.0, "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 03dce981375..74a8e2565ba 100644 --- a/x-pack/docs/en/watcher/actions/slack.asciidoc +++ b/x-pack/docs/en/watcher/actions/slack.asciidoc @@ -4,11 +4,11 @@ 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. @@ -36,7 +36,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 @@ -140,7 +140,7 @@ aggregation and the Slack action: generated by the transform. [[slack-action-attributes]] -==== Slack Action Attributes +==== Slack action attributes [cols=",^,", options="header"] |====== @@ -168,7 +168,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,11 +207,11 @@ bin/elasticsearch-keystore add xpack.notification.slack.account.monitoring.secur [WARNING] ====== You can no longer configure Slack accounts using `elasticsearch.yml` settings. -Please use {es}'s secure {ref}/secure-settings.html[keystore] method instead. +Please use {es}'s secure <> method instead. ====== -You can specify defaults for the {ref}/notification-settings.html#slack-account-attributes[Slack -notification attributes]: +You can specify defaults for the +<>: [source,yaml] -------------------------------------------------- @@ -233,7 +233,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 ce326f74ae3..e423aa56fd2 100644 --- a/x-pack/docs/en/watcher/actions/webhook.asciidoc +++ b/x-pack/docs/en/watcher/actions/webhook.asciidoc @@ -1,14 +1,13 @@ [role="xpack"] [[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. @@ -33,9 +32,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 @@ -77,8 +76,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]] @@ -136,7 +136,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"] |====== @@ -149,23 +149,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 f3803ea713b..6995d88a2f6 100644 --- a/x-pack/docs/en/watcher/condition.asciidoc +++ b/x-pack/docs/en/watcher/condition.asciidoc @@ -5,29 +5,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 <>. 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 8bf60d0e77b..bba7b1696e6 100644 --- a/x-pack/docs/en/watcher/condition/always.asciidoc +++ b/x-pack/docs/en/watcher/condition/always.asciidoc @@ -1,15 +1,15 @@ [role="xpack"] [[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 1e9d3113e8c..1e8ae5d9cbf 100644 --- a/x-pack/docs/en/watcher/condition/array-compare.asciidoc +++ b/x-pack/docs/en/watcher/condition/array-compare.asciidoc @@ -1,20 +1,20 @@ [role="xpack"] [[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 @@ -39,14 +39,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 b3938ba9758..3bb0ec77c8f 100644 --- a/x-pack/docs/en/watcher/condition/compare.asciidoc +++ b/x-pack/docs/en/watcher/condition/compare.asciidoc @@ -1,13 +1,13 @@ [role="xpack"] [[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 @@ -31,13 +31,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] -------------------------------------------------- @@ -93,7 +93,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 84d8a74a261..0328601f00e 100644 --- a/x-pack/docs/en/watcher/condition/never.asciidoc +++ b/x-pack/docs/en/watcher/condition/never.asciidoc @@ -1,13 +1,13 @@ [role="xpack"] [[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 4aabfc9144c..4dcc23ff25f 100644 --- a/x-pack/docs/en/watcher/condition/script.asciidoc +++ b/x-pack/docs/en/watcher/condition/script.asciidoc @@ -1,15 +1,14 @@ [role="xpack"] [[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`: @@ -23,11 +22,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 @@ -48,7 +47,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 @@ -65,10 +64,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] -------------------------------------------------- @@ -80,8 +80,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] -------------------------------------------------- @@ -96,14 +96,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 622a96a64b4..716da9676c8 100644 --- a/x-pack/docs/en/watcher/customizing-watches.asciidoc +++ b/x-pack/docs/en/watcher/customizing-watches.asciidoc @@ -1,30 +1,31 @@ [role="xpack"] [[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] @@ -42,13 +43,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-body.html#request-body-search-search-type[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 Elasticsearch Query DSL available for you to use. @@ -82,7 +83,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 @@ -112,28 +113,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 @@ -152,7 +153,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 @@ -161,7 +162,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 @@ -183,13 +184,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. @@ -197,19 +198,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 c0bcbec74b1..60e8414f31a 100644 --- a/x-pack/docs/en/watcher/encrypting-data.asciidoc +++ b/x-pack/docs/en/watcher/encrypting-data.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[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 @@ -15,7 +15,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. + @@ -25,8 +25,7 @@ every node in the cluster. -- -. Set the -{ref}/notification-settings.html[`xpack.watcher.encrypt_sensitive_data` setting]: +. Set the <>: + -- @@ -37,8 +36,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 90807d4fc03..377f0c39355 100644 --- a/x-pack/docs/en/watcher/example-watches.asciidoc +++ b/x-pack/docs/en/watcher/example-watches.asciidoc @@ -1,14 +1,14 @@ [role="xpack"] [[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. 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 02133303e60..656e4dbd7aa 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,24 +1,24 @@ [role="xpack"] [[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,console] -------------------------------------------------- @@ -69,7 +69,8 @@ PUT _watcher/watch/cluster_health_watch } -------------------------------------------------- -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,console] -------------------------------------------------- @@ -96,9 +97,12 @@ PUT _watcher/watch/cluster_health_watch } -------------------------------------------------- -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 @@ -120,9 +124,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. @@ -174,11 +178,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. @@ -246,7 +250,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. @@ -264,13 +268,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,console] ------------------------------------------------------- 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 cdb4362f5b3..7883d528950 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,6 +1,6 @@ [role="xpack"] [[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. @@ -189,7 +189,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: @@ -291,7 +291,7 @@ PUT _watcher/watch/meetup } -------------------------------------------------- -<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 fa389c9ecf0..3107caa02aa 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,6 +1,6 @@ [role="xpack"] [[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. @@ -152,7 +152,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 8b95f905c09..7001097aab1 100644 --- a/x-pack/docs/en/watcher/getting-started.asciidoc +++ b/x-pack/docs/en/watcher/getting-started.asciidoc @@ -4,7 +4,8 @@ TIP: To complete these steps, you must obtain a license that includes the {alert-features}. For more information about Elastic license levels, see -https://www.elastic.co/subscriptions and <>. +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: @@ -17,14 +18,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,console] @@ -74,9 +75,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 +108,7 @@ PUT _watcher/watch/log_error_watch } -------------------------------------------------- -<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 @@ -149,11 +150,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. @@ -200,7 +201,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,console] -------------------------------------------------- @@ -210,7 +211,7 @@ DELETE _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. @@ -221,11 +222,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 b8dbdc36b9a..1ddfd3f0838 100644 --- a/x-pack/docs/en/watcher/gs-index.asciidoc +++ b/x-pack/docs/en/watcher/gs-index.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[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 d339228dba0..1f733e694fb 100644 --- a/x-pack/docs/en/watcher/how-watcher-works.asciidoc +++ b/x-pack/docs/en/watcher/how-watcher-works.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[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 @@ -16,7 +16,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 @@ -44,7 +44,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,console] @@ -131,7 +131,7 @@ PUT _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/input.asciidoc b/x-pack/docs/en/watcher/input.asciidoc index fd1f017eeb7..45a33379a8e 100644 --- a/x-pack/docs/en/watcher/input.asciidoc +++ b/x-pack/docs/en/watcher/input.asciidoc @@ -9,12 +9,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 87d4944d88f..7ff39d97d29 100644 --- a/x-pack/docs/en/watcher/input/chain.asciidoc +++ b/x-pack/docs/en/watcher/input/chain.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[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 @@ -45,12 +45,12 @@ 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 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 e9d71ead887..bd48d339d64 100644 --- a/x-pack/docs/en/watcher/input/http.asciidoc +++ b/x-pack/docs/en/watcher/input/http.asciidoc @@ -1,10 +1,10 @@ [role="xpack"] [[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: @@ -14,15 +14,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`. @@ -43,7 +42,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: @@ -67,8 +66,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] -------------------------------------------------- @@ -90,7 +88,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 @@ -138,9 +136,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 @@ -161,7 +159,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 @@ -177,7 +175,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"] |====== @@ -190,17 +188,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 @@ -225,7 +223,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 729a7c7d56a..9533a450395 100644 --- a/x-pack/docs/en/watcher/input/search.asciidoc +++ b/x-pack/docs/en/watcher/input/search.asciidoc @@ -1,16 +1,15 @@ [role="xpack"] [[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-body.html#request-body-search-search-type[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 @@ -84,7 +83,7 @@ watch payload: ==== 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: @@ -164,7 +163,7 @@ accurately. |====== | 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`. @@ -172,21 +171,21 @@ accurately. | `request.indices` | no | - | The indices to search. If omitted, all indices 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 d92f01e1637..e69c79f53e1 100644 --- a/x-pack/docs/en/watcher/input/simple.asciidoc +++ b/x-pack/docs/en/watcher/input/simple.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[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 f24f0b89a0e..7cef48d6e33 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 63e88001a4b..96ea3f5e23d 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 325f37bf325..98c4220e68c 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 4d37b910fd1..a019db93374 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 34f2b8aa1e7..6379c09ed23 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 e4fcd86d85c..f7a8c92fc20 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 68250418713..7e584efaf03 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/managing-watches.asciidoc b/x-pack/docs/en/watcher/managing-watches.asciidoc index 75939a0be45..ecd499489ec 100644 --- a/x-pack/docs/en/watcher/managing-watches.asciidoc +++ b/x-pack/docs/en/watcher/managing-watches.asciidoc @@ -1,19 +1,19 @@ [role="xpack"] [[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 af45c4d9c1d..d9410f69acb 100644 --- a/x-pack/docs/en/watcher/release-notes.asciidoc +++ b/x-pack/docs/en/watcher/release-notes.asciidoc @@ -120,8 +120,8 @@ March 30, 2016 {ref}/watcher-api-execute-watch.html[Execute Watch API] .New Features -* Added <> -* Added support for adding <> +* Added <> +* Added support for adding <> via HTTP requests and superseding and deprecating the usage of `attach_data` in order to use this feature @@ -158,7 +158,7 @@ December 17, 2015 November 24, 2015 .New Features -* Adds support for <> +* Adds support for <> .Enhancements * Adds support for Elasticsearch 2.1.0. @@ -205,13 +205,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 @@ -274,40 +274,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 18702934d3e..320bc0b30e4 100644 --- a/x-pack/docs/en/watcher/transform.asciidoc +++ b/x-pack/docs/en/watcher/transform.asciidoc @@ -2,10 +2,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 882db6986e0..a00e86bac07 100644 --- a/x-pack/docs/en/watcher/transform/chain.asciidoc +++ b/x-pack/docs/en/watcher/transform/chain.asciidoc @@ -1,16 +1,16 @@ [role="xpack"] [[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 7d93a87a941..24e1ae6bb34 100644 --- a/x-pack/docs/en/watcher/transform/script.asciidoc +++ b/x-pack/docs/en/watcher/transform/script.asciidoc @@ -1,15 +1,15 @@ [role="xpack"] [[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. @@ -33,13 +33,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 @@ -60,5 +60,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 4fc203bc3d3..1e65137f282 100644 --- a/x-pack/docs/en/watcher/transform/search.asciidoc +++ b/x-pack/docs/en/watcher/transform/search.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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: @@ -48,35 +48,35 @@ 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-body.html#request-body-search-search-type[type]. +| `request.search_type` | no | query_then_fetch | The search <>. | `request.indices` | no | all indices | One or more indices to search on. | `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, @@ -85,11 +85,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 @@ -130,7 +130,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 222ec9e1036..a0852b0470e 100644 --- a/x-pack/docs/en/watcher/trigger.asciidoc +++ b/x-pack/docs/en/watcher/trigger.asciidoc @@ -8,6 +8,6 @@ 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. 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 a8a5fb4b32e..0c9bffb9359 100644 --- a/x-pack/docs/en/watcher/trigger/schedule.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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 @@ -15,7 +15,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 a5d05f8666d..f24c01bd2de 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/cron.asciidoc @@ -2,7 +2,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 @@ -13,10 +13,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: @@ -29,7 +29,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 @@ -50,7 +50,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 @@ -117,7 +117,7 @@ NOTE: Currently, you must specify `?` for either the `day_of_week` or |====== -.Setting Daily Triggers +.Setting daily triggers [options="header"] |====== | Cron Expression | Description @@ -125,7 +125,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 @@ -134,7 +134,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 @@ -144,7 +144,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 @@ -157,7 +157,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 @@ -167,7 +167,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 @@ -187,7 +187,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` @@ -215,7 +215,7 @@ minute during the weekend: ===== Verifying cron expressions The {es} {alert-features} provide a -{ref}/elasticsearch-croneval.html[`elasticsearch-croneval`] command line tool +<> command line tool that you can use to verify that your cron expressions are valid and produce the expected results. This tool is provided in the `$ES_HOME/bin` directory. diff --git a/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc b/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc index 39dbbc7f4fb..6fb91d2a712 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/daily.asciidoc @@ -1,19 +1,19 @@ [role="xpack"] [[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 @@ -31,7 +31,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 @@ -50,7 +50,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 2e462667977..17939096a46 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/hourly.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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. @@ -11,7 +11,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. @@ -31,7 +31,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 14d22a60a33..f4f8b4efd5a 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/interval.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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. @@ -17,7 +17,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 5dae3a96302..b8703ccdd29 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/monthly.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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. @@ -11,7 +11,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 @@ -32,7 +32,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 ddcb4932631..1408489d8d4 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/weekly.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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. @@ -17,7 +17,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 @@ -38,7 +38,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 0a12eb0a8ca..e25d5561c86 100644 --- a/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc +++ b/x-pack/docs/en/watcher/trigger/schedule/yearly.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[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. @@ -21,7 +21,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 @@ -43,7 +43,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