mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-09 06:25:07 +00:00
a22aabcc15
If CI is running tests at exactly 0 or 5 minutes past the hour the ack-watch docs tests may fail with a 409 error if the ack test happens to run at the exact time that the schedule watch is running. This commit changes the public documentation (and the test) for the ack to a feb 29th at noon schedule. Test doc or tests do not really care about the schedule date and this is chosen since it is a valid date, but one that is extremely unlikely to cause issues.
299 lines
8.9 KiB
Plaintext
299 lines
8.9 KiB
Plaintext
[role="xpack"]
|
|
[[watcher-api-ack-watch]]
|
|
=== Ack watch API
|
|
++++
|
|
<titleabbrev>Ack watch</titleabbrev>
|
|
++++
|
|
|
|
<<actions-ack-throttle,Acknowledging a watch>> enables you
|
|
to manually throttle execution of the watch's actions.
|
|
|
|
[[watcher-api-ack-watch-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _watcher/watch/<watch_id>/_ack` +
|
|
|
|
`PUT _watcher/watch/<watch_id>/_ack/<action_id>`
|
|
|
|
[[watcher-api-ack-watch-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* You must have `manage_watcher` cluster privileges to use this API. For more
|
|
information, see <<security-privileges>>.
|
|
|
|
[[watcher-api-ack-watch-desc]]
|
|
==== {api-description-title}
|
|
|
|
An action's _acknowledgement state_ is stored in the
|
|
`status.actions.<id>.ack.state` structure.
|
|
|
|
IMPORTANT: If the specified watch is currently being executed, this API will
|
|
return an error. The reason for this is to prevent overwriting of the watch
|
|
status from a watch execution.
|
|
|
|
[[watcher-api-ack-watch-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<action_id>`::
|
|
(Optional, list) A comma-separated list of the action IDs to acknowledge. If you omit
|
|
this parameter, all of the actions of the watch are acknowledged.
|
|
|
|
`<watch_id>`::
|
|
(Required, string) Identifier for the watch.
|
|
|
|
//[[watcher-api-ack-watch-query-params]]
|
|
//==== {api-query-parms-title}
|
|
|
|
//[[watcher-api-ack-watch-request-body]]
|
|
//==== {api-request-body-title}
|
|
|
|
//[[watcher-api-ack-watch-response-body]]
|
|
//==== {api-response-body-title}
|
|
|
|
//[[watcher-api-ack-watch-response-codes]]
|
|
//==== {api-response-codes-title}
|
|
|
|
[[watcher-api-ack-watch-example]]
|
|
==== {api-examples-title}
|
|
|
|
To demonstrate let's create a new watch:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my_watch
|
|
{
|
|
"trigger" : {
|
|
"schedule" : {
|
|
"yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
|
|
}
|
|
},
|
|
"input": {
|
|
"simple": {
|
|
"payload": {
|
|
"send": "yes"
|
|
}
|
|
}
|
|
},
|
|
"condition": {
|
|
"always": {}
|
|
},
|
|
"actions": {
|
|
"test_index": {
|
|
"throttle_period": "15m",
|
|
"index": {
|
|
"index": "test"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
The current status of a watch and the state of its actions is returned with the
|
|
watch definition when you call the <<watcher-api-get-watch, Get Watch API>>:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
|
|
The action state of a newly-created watch is `awaits_successful_execution`:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_seq_no": 0,
|
|
"_primary_term": 1,
|
|
"_version": 1,
|
|
"_id": "my_watch",
|
|
"status": {
|
|
"version": 1,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "awaits_successful_execution"
|
|
}
|
|
}
|
|
},
|
|
"state": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
|
|
When the watch executes and the condition matches, the value of the `ack.state`
|
|
changes to `ackable`. Let's force execution of the watch and fetch it again to
|
|
check the status:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_execute
|
|
{
|
|
"record_execution" : true
|
|
}
|
|
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
and the action is now in `ackable` state:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_id": "my_watch",
|
|
"_seq_no": 1,
|
|
"_primary_term": 1,
|
|
"_version": 2,
|
|
"status": {
|
|
"version": 2,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "ackable"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"state": ...,
|
|
"execution_state": "executed",
|
|
"last_checked": ...,
|
|
"last_met_condition": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
|
|
Now we can acknowledge it:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my_watch/_ack/test_index
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_id": "my_watch",
|
|
"_seq_no": 2,
|
|
"_primary_term": 1,
|
|
"_version": 3,
|
|
"status": {
|
|
"version": 3,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "acked"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"state": ...,
|
|
"execution_state": "executed",
|
|
"last_checked": ...,
|
|
"last_met_condition": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
|
|
Acknowledging an action throttles further executions of that action until its
|
|
`ack.state` is reset to `awaits_successful_execution`. This happens when the
|
|
condition of the watch is not met (the condition evaluates to `false`).
|
|
|
|
You can acknowledge multiple actions by assigning the `actions` parameter a
|
|
comma-separated list of action ids:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_ack/action1,action2
|
|
--------------------------------------------------
|
|
|
|
To acknowledge all of the actions of a watch, simply omit the `actions`
|
|
parameter:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_ack
|
|
--------------------------------------------------
|
|
// TEST[s/^/POST _watcher\/watch\/my_watch\/_execute\n{ "record_execution" : true }\n/]
|
|
|
|
|
|
The response looks like a get watch response, but only contains the status:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"status": {
|
|
"state": {
|
|
"active": true,
|
|
"timestamp": "2015-05-26T18:04:27.723Z"
|
|
},
|
|
"last_checked": "2015-05-26T18:04:27.753Z",
|
|
"last_met_condition": "2015-05-26T18:04:27.763Z",
|
|
"actions": {
|
|
"test_index": {
|
|
"ack" : {
|
|
"timestamp": "2015-05-26T18:04:27.713Z",
|
|
"state": "acked"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.733Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.773Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"execution_state": "executed",
|
|
"version": 2
|
|
}
|
|
}
|
|
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"last_checked": "2015-05-26T18:04:27.753Z"/"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": "2015-05-26T18:04:27.763Z"/"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.state.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.713Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.733Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.773Z"/"timestamp": "$body.status.actions.test_index.last_successful_execution.timestamp"/]
|