honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Move watcher APIs to Elasticsearch Ref (elastic/x-pack-elasticsearch#1869) 

* [DOCS] Move watcher APIs to Elasticsearch Ref

* [DOCS] Update links to Watcher APIs

Original commit: elastic/x-pack-elasticsearch@5b6e903366
This commit is contained in:
Lisa Cawley 2017-06-27 17:16:51 -07:00 committed by GitHub
parent a68fb27a23
commit b9a7dcdcc4
22 changed files with 102 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/en/rest-api/index.asciidoc
View File

@ -8,7 +8,7 @@
* <<info-api, Info API>>
//* <<security-api, Security APIs>>
//* <<watcher-api, Watcher APIs>>
* <<watcher-api, Watcher APIs>>
* <<graph-api, Graph APIs>>
* <<ml-apis, Machine Learning APIs>>
* <<ml-api-definitions, Definitions>>
@ -117,8 +117,7 @@ GET /_xpack?human=false
//include::security.asciidoc[]
//include::watcher.asciidoc[]
include::watcher.asciidoc[]
include::graph.asciidoc[]
include::ml-api.asciidoc[]
include::defs.asciidoc[]

1
docs/en/rest-api/watcher.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api]]
== Watcher APIs

3
docs/en/rest-api/watcher/ack-watch.asciidoc
View File

@ -1,7 +1,8 @@
[role="xpack"]
[[watcher-api-ack-watch]]
=== Ack Watch API
<<actions-ack-throttle, Acknowledging>> a watch enables you to manually throttle
{xpack-ref}actions.html#actions-ack-throttle[Acknowledging a watch] enables you to manually throttle
execution of the watch's actions. An action's _acknowledgement state_ is stored
in the `status.actions.<id>.ack.state` structure.

6
docs/en/rest-api/watcher/activate-watch.asciidoc
View File

@ -1,8 +1,10 @@
[role="xpack"]
[[watcher-api-activate-watch]]
=== Activate Watch API
A watch can be either <<watch-active-state, active or inactive>>. This API enables
you to activate a currently inactive watch.
A watch can be either
{xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. 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 <<watcher-api-get-watch, Get Watch API>>:

6
docs/en/rest-api/watcher/deactivate-watch.asciidoc
View File

@ -1,8 +1,10 @@
[role="xpack"]
[[watcher-api-deactivate-watch]]
=== Deactivate Watch API
A watch can be either <<watch-active-state, active or inactive>>. This API
enables you to deactivate a currently active watch.
A watch can be either
{xpack-ref}/how-watcher-works.html#watch-active-state[active or inactive]. 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 <<watcher-api-get-watch, Get Watch API>>:

2
docs/en/rest-api/watcher/delete-watch.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-delete-watch]]
=== Delete Watch API
@ -52,4 +53,3 @@ DELETE _xpack/watcher/watch/my_watch?master_timeout=30s
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]

18
docs/en/rest-api/watcher/execute-watch.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-execute-watch]]
=== Execute Watch API
@ -30,8 +31,8 @@ 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
<<condition-always, Always>> Condition. This can also be
specified as a HTTP parameter.
{xpack-ref}/condition-always.html[Always Condition].
This can also be specified as a HTTP parameter.
| `alternative_input` | no | null | When present, the watch uses this object as a payload
instead of executing its own input.
@ -46,7 +47,8 @@ This API supports the following fields:
watch is updated, possibly throttling subsequent executions.
This can also be specified as a HTTP parameter.
| `watch` | no | null | When present, this <<watch-definition, watch>> is used
| `watch` | no | null | When present, this
{xpack-ref}/how-watcher-works.html#watch-definition[watch] is used
instead of the one specified in the request. This watch is
not persisted to the index and record_execution cannot be set.
|======
@ -201,11 +203,11 @@ are five possible modes an action can be associated with:
| Name | Description
| `simulate` | The action execution will be simulated. Each action type
define its own simulation operation mode. For example, The
<<actions-email, email>> action will create the email that
would have been sent but will not actually send it. In this
mode, the action may be throttled if the current state
of the watch indicates it should be.
define its own simulation operation mode. For example, the
{xpack-ref}/actions-email.html[email] action will create
the email that would have been sent but will not actually
send it. In this mode, the action may be throttled if the
current state of the watch indicates it should be.
| `force_simulate` | Similar to the the `simulate` mode, except the action will
not be throttled even if the current state of the watch

1
docs/en/rest-api/watcher/get-watch.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-get-watch]]
=== Get Watch API

24
docs/en/rest-api/watcher/put-watch.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-put-watch]]
=== Put Watch API
@ -77,17 +78,17 @@ A watch has the following fields:
|======
| Name | Description
| `trigger` | The <<trigger, trigger>> that defines when the watch
should run.
| `trigger` | The {xpack-ref}/trigger.html[trigger] that defines when
the watch should run.
| `input` | The <<input, input>> that defines the input that loads the
data for the watch.
| `input` | The {xpack-ref}/input.html[input] that defines the input
that loads the data for the watch.
| `condition` | The <<condition, condition>> that defines if the actions
should be run.
| `condition` | The {xpack-ref}/condition.html[condition] that defines if
the actions should be run.
| `actions` | The list of <<actions, actions>> that will be run if the
condition matches
| `actions` | The list of {xpack-ref}/actions.html[actions] that will be
run if the condition matches
| `metadata` | Metadata json that will be copied into the history entries.
@ -116,9 +117,10 @@ PUT _xpack/watcher/watch/my-watch?master_timeout=30s
[[watcher-api-put-watch-active-state]]
==== Controlling Default Active State
When adding a watch you can also define its initial <<watch-active-state, active state>>.
You do that by setting the `active` parameter. The following command add a watch
and sets it to be inactive by default:
When adding a watch you can also define its initial
{xpack-ref}/how-watcher-works.html#watch-active-state[active state]. You do that
by setting the `active` parameter. The following command add a watch and sets it
to be inactive by default:
[source,js]
--------------------------------------------------

1
docs/en/rest-api/watcher/restart.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-restart]]
=== Restart API

1
docs/en/rest-api/watcher/start.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-start]]
=== Start API

1
docs/en/rest-api/watcher/stats.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-stats]]
=== Stats API

1
docs/en/rest-api/watcher/stop.asciidoc
View File

@ -1,3 +1,4 @@
[role="xpack"]
[[watcher-api-stop]]
=== Stop API

4
docs/en/rest-api/xindex.asciidoc
View File

@ -7,7 +7,7 @@
* <<info-api, Info API>>
* <<security-api, Security APIs>>
* <<watcher-api, Watcher APIs>>
* {ref}/watcher-api.html[Watcher APIs]
* <<graph-api, Graph APIs>>
* {ref}/ml-apis.html[Machine Learning APIs]
* {ref}/ml-api-definitions.html[Definitions]
@ -115,6 +115,4 @@ GET /_xpack?human=false
include::security.asciidoc[]
include::watcher.asciidoc[]
include::graph.asciidoc[]

31
docs/en/watcher/actions.asciidoc
View File

@ -2,21 +2,21 @@
== Actions
When a watch's condition is met, it's actions are executed unless it is being
<<actions-ack-throttle, throttled>>. 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
<<actions-ack-throttle, throttled>>. 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.
NOTE: If no actions are defined for a watch, no actions are executed.
NOTE: If no actions are defined for a watch, no actions are executed.
However, a `watch_record` is still written to the watch history.
Actions have access to the payload in the execution context. They can use it to
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:
<<actions-email, email>>, <<actions-webhook, webhook>>, <<actions-index, index>>,
<<actions-logging, logging>>, <<actions-hipchat, hipchat>>, <<actions-slack,
{watcher} supports the following types of actions:
<<actions-email, email>>, <<actions-webhook, webhook>>, <<actions-index, index>>,
<<actions-logging, logging>>, <<actions-hipchat, hipchat>>, <<actions-slack,
Slack>>, and <<actions-pagerduty, pagerduty>>.
[float]
@ -161,14 +161,15 @@ xpack.watcher.execution.default_throttle_period: 15m
--------------------------------------------------
{watcher} also supports acknowledgement-based throttling. You can acknowledge a
watch using the <<watcher-api-ack-watch, Ack Watch API>> 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`.
watch using the {ref}/watcher-api-ack-watch.html[Ack Watch API] 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 <<watcher-api-ack-watch,Ack Watch API>>:
To acknowledge an action, you use the
{ref}/watcher-api-ack-watch.html[Ack Watch API]:
[source,js]
----------------------------------------------------------------------

4
docs/en/watcher/example-watches/example-watch-clusterstatus.asciidoc
View File

@ -1,5 +1,5 @@
[[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:
@ -276,7 +276,7 @@ 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 <<watcher-api-delete-watch, DELETE watch>> API:
To remove the watch, use the {ref}/watcher-api-delete-watch.html[DELETE watch API]:
[source,js]
-------------------------------------------------------

19
docs/en/watcher/example-watches/example-watch-meetupdata.asciidoc
View File

@ -46,7 +46,7 @@ output { <2>
[source,she]
----------------------------------------------------------
curl http://stream.meetup.com/2/rsvps | bin/logstash -f livestream.conf
curl http://stream.meetup.com/2/rsvps | bin/logstash -f livestream.conf
---------------------------------------------------------
Now that you're indexing the meetup RSVPs, you can set up a watch that lets you know about events you might be interested in. For example, let's create a watch that runs every hour, looks for events that talk about about _Open Source_, and sends an email with information about the events.
@ -135,7 +135,7 @@ To set up the watch:
}
},
--------------------------------------------------
<1> Elasticsearch Date math is used to select the Logstash indices that contain the meetup data. The second pattern is needed in case the previous hour crosses days.
<1> Elasticsearch Date math is used to select the Logstash indices that contain the meetup data. The second pattern is needed in case the previous hour crosses days.
<2> Find all of the RSVPs with `Open Source` as a topic.
<3> Group the RSVPs by city.
<4> Consolidate multiple RSVPs for the same event.
@ -150,16 +150,16 @@ To set up the watch:
. To send an email when _Open Source_ events are found, add an email action:
[source,js]
--------------------------------------------------
"actions": {
"actions": {
"email_me": {
"throttle_period": "10m",
"email": {
"from": "<from:email address>",
"to": "<to:email address>",
"subject": "Open Source Events",
"body": {
"body": {
"html": "Found events matching Open Source: <ul>{{#ctx.payload.aggregations.group_by_city.buckets}}< li>{{key}} ({{doc_count}})<ul>{{#group_by_event.buckets}}
<li><a href=\"{{key}}\">{{get_latest.buckets.0.group_by_event_name.buckets.0.key}}</a>
<li><a href=\"{{key}}\">{{get_latest.buckets.0.group_by_event_name.buckets.0.key}}</a>
({{doc_count}})</li>{{/group_by_event.buckets}}</ul></li>
{{/ctx.payload.aggregations.group_by_city.buckets}}</ul>"
}
@ -260,8 +260,8 @@ PUT _xpack/watcher/watch/meetup
"from": "<username>@<domainname>", <2>
"to": "<username@<domainname>", <3>
"subject": "Open Source events",
"body": {
"html": "Found events matching Open Source: <ul>{{#ctx.payload.aggregations.group_by_city.buckets}}<li>{{key}} ({{doc_count}})<ul>{{#group_by_event.buckets}}<li><a href=\"{{key}}\">{{get_latest.buckets.0.group_by_event_name.buckets.0.key}}</a> ({{doc_count}})</li>{{/group_by_event.buckets}}</ul></li>{{/ctx.payload.aggregations.group_by_city.buckets}}</ul>"
"body": {
"html": "Found events matching Open Source: <ul>{{#ctx.payload.aggregations.group_by_city.buckets}}<li>{{key}} ({{doc_count}})<ul>{{#group_by_event.buckets}}<li><a href=\"{{key}}\">{{get_latest.buckets.0.group_by_event_name.buckets.0.key}}</a> ({{doc_count}})</li>{{/group_by_event.buckets}}</ul></li>{{/ctx.payload.aggregations.group_by_city.buckets}}</ul>"
}
}
}
@ -270,12 +270,13 @@ PUT _xpack/watcher/watch/meetup
--------------------------------------------------
// CONSOLE
<1> The email body can include Mustache templates to reference data in the watch payload. By default,it will be <<email-html-sanitization, sanitized>> to block dangerous content.
<1> The email body can include Mustache templates to reference data in the watch payload. By default,it will be <<email-html-sanitization, sanitized>> 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.
Now that you've created your watch, you can use the <<watcher-api-execute-watch, `_execute`>> API to run it without waiting for the schedule to trigger execution:
Now that you've created your watch, you can use the
{ref}/watcher-api-execute-watch.html[`_execute` API] to run it without waiting for the schedule to trigger execution:
[source,js]
--------------------------------------------------

2
docs/en/watcher/example-watches/watching-time-series-data.asciidoc
View File

@ -211,7 +211,7 @@ PUT _xpack/watcher/watch/rss_watch
[TIP]
=================================================
To execute a watch immediately (without waiting for the schedule to trigger),
use the <<watcher-api-execute-watch, `_execute`>> API:
use the {ref}/watcher-api-execute-watch.html[`_execute` API]:
[source,js]
--------------------------------------------------

8
docs/en/watcher/getting-started.asciidoc
View File

@ -2,7 +2,7 @@
== Getting Started with {watcher}
{Watcher} is automatically enabled when you <<installing-xpack, install
{xpack}>> into Elasticsearch and Kibana.
{xpack}>> into Elasticsearch and Kibana.
[[watch-log-data]]
To set up a watch to start sending alerts:
@ -127,7 +127,7 @@ POST logs/event
// TEST[continued]
Once you add this event, the next time the watch executes its condition will
evaluate to `true`. The condition result is recorded as part of the
evaluate to `true`. The condition result is recorded as part of the
`watch_record` each time the watch executes, so you can verify whether or
not the condition was met by searching the watch history:
@ -202,7 +202,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 <<watcher-api-delete-watch, DELETE watch>> API:
To remove the watch, use the {ref}/watcher-api-delete-watch.html[DELETE watch API]:
[source,js]
--------------------------------------------------
@ -214,7 +214,7 @@ DELETE _xpack/watcher/watch/log_error_watch
[float]
[[required-security-privileges]]
=== Required Security Privileges
To enable users to create and manipulate watches, assign them the `watcher_admin`
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.

18
docs/en/watcher/how-watcher-works.asciidoc
View File

@ -42,8 +42,9 @@ Specify what happens when the watch condition is met.
[[watch-definition-example]]
For example, the following snippet shows a <<watcher-api-put-watch, Put Watch>>
request that defines a watch that looks for log error events:
For example, the following snippet shows a
{ref}/watcher-api-put-watch.html[Put Watch] request that defines a watch that
looks for log error events:
[source,js]
--------------------------------------------------
@ -227,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
<<watcher-api-put-watch-active-state, `active`>> parameter to _inactive_.
To deactivate an existing watch, use the <<watcher-api-deactivate-watch, D
eactivate Watch API>>. To reactivate an inactive watch, use the
<<watcher-api-activate-watch, Activate Watch API>>.
{ref}/watcher-api-put-watch.html#watcher-api-put-watch-active-state[`active`]
parameter to _inactive_. To deactivate an existing watch, use the
{ref}/watcher-api-deactivate-watch.html[Deactivate Watch API]. To reactivate an inactive watch, use the
{ref}/watcher-api-activate-watch.html[Activate Watch API].
NOTE: You can use the <<watcher-api-execute-watch, Execute Watch API>> to
force the execution of a watch even when it is inactive.
NOTE: You can use the {ref}/watcher-api-execute-watch.html[Execute Watch API]
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
have a watch that monitors an external system and you need to take that system
@ -434,4 +435,3 @@ references the `email_notification_subject` template:
}
}
----------------------------------------------------------------------

12
docs/en/watcher/managing-watches.asciidoc
View File

@ -3,12 +3,12 @@
{watcher} provides as set of APIs you can use to manage your watches:
* Use the <<watcher-api-put-watch>> to add or update watches
* Use the <<watcher-api-get-watch>> to retrieve watches
* Use the <<watcher-api-delete-watch>> to delete watches
* Use the <<watcher-api-activate-watch>> to activate watches
* Use the <<watcher-api-deactivate-watch>> to deactivate watches
* Use the <<watcher-api-ack-watch>> to acknowledge 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
[float]
[[listing-watches]]

22
docs/en/watcher/release-notes.asciidoc
View File

@ -32,7 +32,7 @@ in the watch history.
.Enhancements
* Hostname verification can be disabled for Watcher
HTTP actions.
* Running watches can be updated and deleted.
* Running watches can be updated and deleted.
[float]
==== 2.4.0
@ -88,14 +88,14 @@ May 18, 2016
April 26, 2016
.Bug Fixes
* All SMTP connection timeouts are now set to two minutes by default to prevent
* All SMTP connection timeouts are now set to two minutes by default to prevent
a watch from getting stuck.
* HTTP headers from responses that contained dots led to exceptions when the
HTTP response was stored in the watch history. All dots in any header names
are now replaced with underscores. For example, a header called `foo.bar`
* HTTP headers from responses that contained dots led to exceptions when the
HTTP response was stored in the watch history. All dots in any header names
are now replaced with underscores. For example, a header called `foo.bar`
becomes `foo_bar`
* Hipchat action: Fall back to the default Hipchat color and format if they
are not specified at the account level or within the action itself, instead
* Hipchat action: Fall back to the default Hipchat color and format if they
are not specified at the account level or within the action itself, instead
of failing.
[float]
@ -116,7 +116,7 @@ March 30, 2016
.Enhancement
* Support `url` in http requests as a shortcut for `path`, `scheme`, `port`, `params`
* Support `ignore_condition` and `record_execution` as parameters in the
<<watcher-api-execute-watch, Execute Watch API>>
{ref}/watcher-api-execute-watch.html[Execute Watch API]
.New Features
* Added <<actions-pagerduty, PagerDuty action>>
@ -207,8 +207,8 @@ October 28, 2015
* Added new <<actions-hipchat, HipChat Action>>
* Added new <<actions-slack, Slack Action>>
* Watches now have an <<watch-active-state, active state>>. In addition, a new
API was added to <<watcher-api-activate-watch, activate>>/<<watcher-api-deactivate-watch, deactivate>>
registered watches.
API was added to {ref}/watcher-api-activate-watch.html[activate]
/{ref}watcher-api-deactivate-watch.html[deactivate] registered watches.
* Added new <<condition-array-compare, array_compare>>, that can compare an array
of values in the <<watch-execution-context, Watch Execution Context Model>>
to a given value.
@ -264,7 +264,7 @@ June 25, 2015
action, `search` input, and `search` transform.
* You must now explicitly specify the unit when configuring any time value.
(Numeric-only values are no longer supported.)
* Cleaned up the <<watcher-api-get-watch, Get Watch API>> response.
* Cleaned up the {ref}/watcher-api-get-watch.html[Get Watch API] response.
* Cleaned up the <<watcher-api-stats, Stats API>> response.