diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index cf7870f39b..504bf63a3f 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -37888,7 +37888,7 @@ "watcher" ], "summary": "Acknowledge a watch", - "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", + "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", "operationId": "watcher-ack-watch", "parameters": [ { @@ -37906,7 +37906,7 @@ "watcher" ], "summary": "Acknowledge a watch", - "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", + "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", "operationId": "watcher-ack-watch-1", "parameters": [ { @@ -37926,7 +37926,7 @@ "watcher" ], "summary": "Acknowledge a watch", - "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", + "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", "operationId": "watcher-ack-watch-2", "parameters": [ { @@ -37947,7 +37947,7 @@ "watcher" ], "summary": "Acknowledge a watch", - "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", + "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", "operationId": "watcher-ack-watch-3", "parameters": [ { @@ -38063,7 +38063,7 @@ { "in": "path", "name": "id", - "description": "Watch ID", + "description": "The watch identifier.", "required": true, "deprecated": false, "schema": { @@ -38190,7 +38190,7 @@ { "in": "path", "name": "id", - "description": "Watch ID", + "description": "The watch identifier.", "required": true, "deprecated": false, "schema": { @@ -38235,7 +38235,7 @@ "watcher" ], "summary": "Run a watch", - "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", + "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", "operationId": "watcher-execute-watch", "parameters": [ { @@ -38259,7 +38259,7 @@ "watcher" ], "summary": "Run a watch", - "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", + "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", "operationId": "watcher-execute-watch-1", "parameters": [ { @@ -38285,7 +38285,7 @@ "watcher" ], "summary": "Run a watch", - "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", + "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", "operationId": "watcher-execute-watch-2", "parameters": [ { @@ -38306,7 +38306,7 @@ "watcher" ], "summary": "Run a watch", - "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", + "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", "operationId": "watcher-execute-watch-3", "parameters": [ { @@ -38329,7 +38329,7 @@ "watcher" ], "summary": "Query watches", - "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.", + "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.\n\nNote that only the `_id` and `metadata.*` fields are queryable or sortable.", "operationId": "watcher-query-watches", "requestBody": { "$ref": "#/components/requestBodies/watcher.query_watches" @@ -38346,7 +38346,7 @@ "watcher" ], "summary": "Query watches", - "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.", + "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.\n\nNote that only the `_id` and `metadata.*` fields are queryable or sortable.", "operationId": "watcher-query-watches-1", "requestBody": { "$ref": "#/components/requestBodies/watcher.query_watches" @@ -38399,6 +38399,7 @@ "watcher" ], "summary": "Get Watcher statistics", + "description": "This API always returns basic metrics.\nYou retrieve more metrics by using the metric parameter.", "operationId": "watcher-stats", "parameters": [ { @@ -38422,6 +38423,7 @@ "watcher" ], "summary": "Get Watcher statistics", + "description": "This API always returns basic metrics.\nYou retrieve more metrics by using the metric parameter.", "operationId": "watcher-stats-1", "parameters": [ { @@ -38454,7 +38456,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -90510,6 +90512,7 @@ "type": "object", "properties": { "current_watches": { + "description": "The current executing watches metric gives insight into the watches that are currently being executed by Watcher.\nAdditional information is shared per watch that is currently executing.\nThis information includes the `watch_id`, the time its execution started and its current execution phase.\nTo include this metric, the `metric` option should be set to `current_watches` or `_all`.\nIn addition you can also specify the `emit_stacktraces=true` parameter, which adds stack traces for each watch that is being run.\nThese stack traces can give you more insight into an execution of a watch.", "type": "array", "items": { "$ref": "#/components/schemas/watcher.stats:WatchRecordStats" @@ -90519,12 +90522,14 @@ "$ref": "#/components/schemas/watcher._types:ExecutionThreadPool" }, "queued_watches": { + "description": "Watcher moderates the execution of watches such that their execution won't put too much pressure on the node and its resources.\nIf too many watches trigger concurrently and there isn't enough capacity to run them all, some of the watches are queued, waiting for the current running watches to finish.s\nThe queued watches metric gives insight on these queued watches.\n\nTo include this metric, the `metric` option should include `queued_watches` or `_all`.", "type": "array", "items": { "$ref": "#/components/schemas/watcher.stats:WatchRecordQueuedStats" } }, "watch_count": { + "description": "The number of watches currently registered.", "type": "number" }, "watcher_state": { @@ -90605,9 +90610,11 @@ "type": "object", "properties": { "max_size": { + "description": "The largest size of the execution thread pool, which indicates the largest number of concurrent running watches.", "type": "number" }, "queue_size": { + "description": "The number of watches that were triggered and are currently queued.", "type": "number" } }, @@ -95966,9 +95973,11 @@ "type": "object", "properties": { "count": { + "description": "The total number of watches found.", "type": "number" }, "watches": { + "description": "A list of watches based on the `from`, `size`, or `search_after` request body parameters.", "type": "array", "items": { "$ref": "#/components/schemas/watcher._types:QueryWatch" @@ -105376,7 +105385,7 @@ "watcher.ack_watch#watch_id": { "in": "path", "name": "watch_id", - "description": "Watch ID", + "description": "The watch identifier.", "required": true, "deprecated": false, "schema": { @@ -105387,7 +105396,7 @@ "watcher.ack_watch#action_id": { "in": "path", "name": "action_id", - "description": "A comma-separated list of the action ids to be acked", + "description": "A comma-separated list of the action identifiers to acknowledge.\nIf you omit this parameter, all of the actions of the watch are acknowledged.", "required": true, "deprecated": false, "schema": { @@ -105398,7 +105407,7 @@ "watcher.activate_watch#watch_id": { "in": "path", "name": "watch_id", - "description": "Watch ID", + "description": "The watch identifier", "required": true, "deprecated": false, "schema": { @@ -105409,7 +105418,7 @@ "watcher.deactivate_watch#watch_id": { "in": "path", "name": "watch_id", - "description": "Watch ID", + "description": "The watch identifier.", "required": true, "deprecated": false, "schema": { @@ -105420,7 +105429,7 @@ "watcher.execute_watch#id": { "in": "path", "name": "id", - "description": "Identifier for the watch.", + "description": "The watch identifier.", "required": true, "deprecated": false, "schema": { @@ -105441,7 +105450,7 @@ "watcher.put_watch#id": { "in": "path", "name": "id", - "description": "Watch ID", + "description": "The identifier for the watch.", "required": true, "deprecated": false, "schema": { @@ -105452,7 +105461,7 @@ "watcher.put_watch#active": { "in": "query", "name": "active", - "description": "Specify whether the watch is in/active by default", + "description": "The initial state of the watch.\nThe default value is `true`, which means the watch is active by default.", "deprecated": false, "schema": { "type": "boolean" @@ -108408,7 +108417,7 @@ "type": "boolean" }, "record_execution": { - "description": "When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter.", + "description": "When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time.\nIn addition, the status of the watch is updated, possibly throttling subsequent runs.\nThis can also be specified as an HTTP parameter.", "type": "boolean" }, "simulated_actions": { @@ -108432,6 +108441,7 @@ "type": "object", "properties": { "actions": { + "description": "The list of actions that will be run if the condition matches.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/watcher._types:Action" @@ -108447,7 +108457,10 @@ "$ref": "#/components/schemas/_types:Metadata" }, "throttle_period": { - "type": "string" + "$ref": "#/components/schemas/_types:Duration" + }, + "throttle_period_in_millis": { + "$ref": "#/components/schemas/_types:DurationValueUnitMillis" }, "transform": { "$ref": "#/components/schemas/_types:TransformContainer" @@ -108467,11 +108480,11 @@ "type": "object", "properties": { "from": { - "description": "The offset from the first result to fetch. Needs to be non-negative.", + "description": "The offset from the first result to fetch.\nIt must be non-negative.", "type": "number" }, "size": { - "description": "The number of hits to return. Needs to be non-negative.", + "description": "The number of hits to return.\nIt must be non-negative.", "type": "number" }, "query": { diff --git a/output/schema/schema.json b/output/schema/schema.json index a866703da9..a24338c8d3 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -20886,8 +20886,9 @@ "stability": "stable" } }, - "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-ack-watch.html", + "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", + "docId": "watcher-api-ack-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-ack-watch.html", "name": "watcher.ack_watch", "privileges": { "cluster": [ @@ -20930,7 +20931,8 @@ } }, "description": "Activate a watch.\nA watch can be either active or inactive.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-activate-watch.html", + "docId": "watcher-api-activate-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-activate-watch.html", "extDocId": "watcher-works", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html", "name": "watcher.activate_watch", @@ -20968,7 +20970,8 @@ } }, "description": "Deactivate a watch.\nA watch can be either active or inactive.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-deactivate-watch.html", + "docId": "watcher-api-deactivate-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-deactivate-watch.html", "extDocId": "watcher-works", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html", "name": "watcher.deactivate_watch", @@ -21006,7 +21009,8 @@ } }, "description": "Delete a watch.\nWhen the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.\n\nDeleting a watch does not delete any watch execution records related to this watch from the watch history.\n\nIMPORTANT: Deleting a watch must be done by using only this API.\nDo not delete the watch directly from the `.watches` index using the Elasticsearch delete document API\nWhen Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-delete-watch.html", + "docId": "watcher-api-delete-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-delete-watch.html", "name": "watcher.delete_watch", "privileges": { "cluster": [ @@ -21040,8 +21044,9 @@ "stability": "stable" } }, - "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-execute-watch.html", + "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", + "docId": "watcher-api-execute-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-execute-watch.html", "name": "watcher.execute_watch", "privileges": { "cluster": [ @@ -21116,7 +21121,8 @@ } }, "description": "Get a watch.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-get-watch.html", + "docId": "watcher-api-get-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-get-watch.html", "name": "watcher.get_watch", "privileges": { "cluster": [ @@ -21151,7 +21157,8 @@ } }, "description": "Create or update a watch.\nWhen a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.\nTypically for the `schedule` trigger, the scheduler is the trigger engine.\n\nIMPORTANT: You must use Kibana or this API to create a watch.\nDo not add a watch directly to the `.watches` index by using the Elasticsearch index API.\nIf Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.\n\nWhen you add a watch you can also define its initial active state by setting the *active* parameter.\n\nWhen Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.\nIf the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html", + "docId": "watcher-api-put-watch", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-put-watch.html", "name": "watcher.put_watch", "privileges": { "cluster": [ @@ -21190,8 +21197,9 @@ "stability": "stable" } }, - "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-query-watches.html", + "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.\n\nNote that only the `_id` and `metadata.*` fields are queryable or sortable.", + "docId": "watcher-api-query-watches", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-query-watches.html", "name": "watcher.query_watches", "privileges": { "cluster": [ @@ -21230,7 +21238,8 @@ } }, "description": "Start the watch service.\nStart the Watcher service if it is not already running.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html", + "docId": "watcher-api-start", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-start.html", "name": "watcher.start", "privileges": { "cluster": [ @@ -21265,8 +21274,9 @@ "stability": "stable" } }, - "description": "Get Watcher statistics.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stats.html", + "description": "Get Watcher statistics.\nThis API always returns basic metrics.\nYou retrieve more metrics by using the metric parameter.", + "docId": "watcher-api-stats", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-stats.html", "name": "watcher.stats", "privileges": { "cluster": [ @@ -21307,7 +21317,8 @@ } }, "description": "Stop the watch service.\nStop the Watcher service if it is running.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stop.html", + "docId": "watcher-api-stop", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-stop.html", "name": "watcher.stop", "privileges": { "cluster": [ @@ -218432,6 +218443,7 @@ }, "properties": [ { + "description": "The largest size of the execution thread pool, which indicates the largest number of concurrent running watches.", "name": "max_size", "required": true, "type": { @@ -218443,6 +218455,7 @@ } }, { + "description": "The number of watches that were triggered and are currently queued.", "name": "queue_size", "required": true, "type": { @@ -218454,7 +218467,7 @@ } } ], - "specLocation": "watcher/_types/Execution.ts#L94-L97" + "specLocation": "watcher/_types/Execution.ts#L94-L103" }, { "kind": "interface", @@ -221237,7 +221250,7 @@ "body": { "kind": "no_body" }, - "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.", + "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions..ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.\n\nAcknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.\nThis happens when the condition of the watch is not met (the condition evaluates to false).", "inherits": { "type": { "name": "RequestBase", @@ -221250,7 +221263,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The watch identifier.", "name": "watch_id", "required": true, "type": { @@ -221262,7 +221275,7 @@ } }, { - "description": "A comma-separated list of the action ids to be acked", + "description": "A comma-separated list of the action identifiers to acknowledge.\nIf you omit this parameter, all of the actions of the watch are acknowledged.", "name": "action_id", "required": false, "type": { @@ -221275,7 +221288,7 @@ } ], "query": [], - "specLocation": "watcher/ack_watch/WatcherAckWatchRequest.ts#L23-L40" + "specLocation": "watcher/ack_watch/WatcherAckWatchRequest.ts#L23-L51" }, { "kind": "response", @@ -221322,7 +221335,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The watch identifier", "name": "watch_id", "required": true, "type": { @@ -221335,7 +221348,7 @@ } ], "query": [], - "specLocation": "watcher/activate_watch/WatcherActivateWatchRequest.ts#L23-L35" + "specLocation": "watcher/activate_watch/WatcherActivateWatchRequest.ts#L23-L39" }, { "kind": "response", @@ -221382,7 +221395,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The watch identifier.", "name": "watch_id", "required": true, "type": { @@ -221395,7 +221408,7 @@ } ], "query": [], - "specLocation": "watcher/deactivate_watch/DeactivateWatchRequest.ts#L23-L35" + "specLocation": "watcher/deactivate_watch/DeactivateWatchRequest.ts#L23-L39" }, { "kind": "response", @@ -221442,7 +221455,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The watch identifier.", "name": "id", "required": true, "type": { @@ -221455,7 +221468,7 @@ } ], "query": [], - "specLocation": "watcher/delete_watch/DeleteWatchRequest.ts#L23-L40" + "specLocation": "watcher/delete_watch/DeleteWatchRequest.ts#L23-L44" }, { "kind": "response", @@ -221567,7 +221580,7 @@ } }, { - "description": "When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter.", + "description": "When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time.\nIn addition, the status of the watch is updated, possibly throttling subsequent runs.\nThis can also be specified as an HTTP parameter.", "name": "record_execution", "required": false, "serverDefault": false, @@ -221591,7 +221604,7 @@ } }, { - "description": "This structure is parsed as the data of the trigger event that will be used during the watch execution", + "description": "This structure is parsed as the data of the trigger event that will be used during the watch execution.", "name": "trigger_data", "required": false, "type": { @@ -221603,7 +221616,7 @@ } }, { - "description": "When present, this 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.", + "description": "When present, this watch is used instead of the one specified in the request.\nThis watch is not persisted to the index and `record_execution` cannot be set.", "name": "watch", "required": false, "serverDefault": "null", @@ -221617,7 +221630,7 @@ } ] }, - "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.", + "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.\n\nWhen Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches.\nIf your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.\n\nWhen using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.", "inherits": { "type": { "name": "RequestBase", @@ -221630,7 +221643,7 @@ }, "path": [ { - "description": "Identifier for the watch.", + "description": "The watch identifier.", "name": "id", "required": false, "type": { @@ -221657,7 +221670,7 @@ } } ], - "specLocation": "watcher/execute_watch/WatcherExecuteWatchRequest.ts#L28-L86" + "specLocation": "watcher/execute_watch/WatcherExecuteWatchRequest.ts#L28-L95" }, { "kind": "response", @@ -221665,6 +221678,7 @@ "kind": "properties", "properties": [ { + "description": "The watch record identifier as it would be stored in the `.watcher-history` index.", "name": "_id", "required": true, "type": { @@ -221676,6 +221690,7 @@ } }, { + "description": "The watch record document as it would be stored in the `.watcher-history` index.", "name": "watch_record", "required": true, "type": { @@ -221692,7 +221707,7 @@ "name": "Response", "namespace": "watcher.execute_watch" }, - "specLocation": "watcher/execute_watch/WatcherExecuteWatchResponse.ts#L23-L25" + "specLocation": "watcher/execute_watch/WatcherExecuteWatchResponse.ts#L23-L34" }, { "kind": "interface", @@ -221849,7 +221864,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The watch identifier.", "name": "id", "required": true, "type": { @@ -221862,7 +221877,7 @@ } ], "query": [], - "specLocation": "watcher/get_watch/GetWatchRequest.ts#L23-L33" + "specLocation": "watcher/get_watch/GetWatchRequest.ts#L23-L37" }, { "kind": "response", @@ -221963,6 +221978,7 @@ "kind": "properties", "properties": [ { + "description": "The list of actions that will be run if the condition matches.", "name": "actions", "required": false, "type": { @@ -221985,6 +222001,7 @@ } }, { + "description": "The condition that defines if the actions should be run.", "name": "condition", "required": false, "type": { @@ -221996,6 +222013,7 @@ } }, { + "description": "The input that defines the input that loads the data for the watch.", "name": "input", "required": false, "type": { @@ -222007,6 +222025,7 @@ } }, { + "description": "Metadata JSON that will be copied into the history entries.", "name": "metadata", "required": false, "type": { @@ -222018,17 +222037,40 @@ } }, { + "description": "The minimum time between actions being run.\nThe default is 5 seconds.\nThis default can be changed in the config file with the setting `xpack.watcher.throttle.period.default_period`.\nIf both this value and the `throttle_period_in_millis` parameter are specified, Watcher uses the last parameter included in the request.", "name": "throttle_period", "required": false, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "Duration", + "namespace": "_types" + } + } + }, + { + "description": "Minimum time in milliseconds between actions being run. Defaults to 5000. If both this value and the throttle_period parameter are specified, Watcher uses the last parameter included in the request.", + "name": "throttle_period_in_millis", + "required": false, + "type": { + "kind": "instance_of", + "generics": [ + { + "kind": "instance_of", + "type": { + "name": "UnitMillis", + "namespace": "_types" + } + } + ], + "type": { + "name": "DurationValue", + "namespace": "_types" } } }, { + "description": "The transform that processes the watch payload to prepare it for the watch actions.", "name": "transform", "required": false, "type": { @@ -222040,6 +222082,7 @@ } }, { + "description": "The trigger that defines when the watch should run.", "name": "trigger", "required": false, "type": { @@ -222065,7 +222108,7 @@ }, "path": [ { - "description": "Watch ID", + "description": "The identifier for the watch.", "name": "id", "required": true, "type": { @@ -222079,9 +222122,10 @@ ], "query": [ { - "description": "Specify whether the watch is in/active by default", + "description": "The initial state of the watch.\nThe default value is `true`, which means the watch is active by default.", "name": "active", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -222127,7 +222171,7 @@ } } ], - "specLocation": "watcher/put_watch/WatcherPutWatchRequest.ts#L30-L66" + "specLocation": "watcher/put_watch/WatcherPutWatchRequest.ts#L31-L104" }, { "kind": "response", @@ -222206,7 +222250,7 @@ "kind": "properties", "properties": [ { - "description": "The offset from the first result to fetch. Needs to be non-negative.", + "description": "The offset from the first result to fetch.\nIt must be non-negative.", "name": "from", "required": false, "serverDefault": 0, @@ -222219,7 +222263,7 @@ } }, { - "description": "The number of hits to return. Needs to be non-negative.", + "description": "The number of hits to return.\nIt must be non-negative.", "name": "size", "required": false, "serverDefault": 10, @@ -222232,7 +222276,7 @@ } }, { - "description": "Optional, query filter watches to be returned.", + "description": "A query that filters the watches to be returned.", "name": "query", "required": false, "type": { @@ -222244,7 +222288,9 @@ } }, { - "description": "Optional sort definition.", + "description": "One or more fields used to sort the search results.", + "extDocId": "sort-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", "required": false, "type": { @@ -222256,7 +222302,9 @@ } }, { - "description": "Optional search After to do pagination using last hit’s sort values.", + "description": "Retrieve the next page of hits using a set of sort values from the previous page.", + "extDocId": "search-after", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after", "name": "search_after", "required": false, "type": { @@ -222269,7 +222317,7 @@ } ] }, - "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.", + "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.\n\nNote that only the `_id` and `metadata.*` fields are queryable or sortable.", "inherits": { "type": { "name": "RequestBase", @@ -222282,7 +222330,7 @@ }, "path": [], "query": [], - "specLocation": "watcher/query_watches/WatcherQueryWatchesRequest.ts#L25-L51" + "specLocation": "watcher/query_watches/WatcherQueryWatchesRequest.ts#L25-L64" }, { "kind": "response", @@ -222290,6 +222338,7 @@ "kind": "properties", "properties": [ { + "description": "The total number of watches found.", "name": "count", "required": true, "type": { @@ -222301,6 +222350,7 @@ } }, { + "description": "A list of watches based on the `from`, `size`, or `search_after` request body parameters.", "name": "watches", "required": true, "type": { @@ -222320,7 +222370,7 @@ "name": "Response", "namespace": "watcher.query_watches" }, - "specLocation": "watcher/query_watches/WatcherQueryWatchesResponse.ts#L23-L28" + "specLocation": "watcher/query_watches/WatcherQueryWatchesResponse.ts#L23-L34" }, { "kind": "request", @@ -222357,7 +222407,7 @@ } } ], - "specLocation": "watcher/start/WatcherStartRequest.ts#L23-L38" + "specLocation": "watcher/start/WatcherStartRequest.ts#L23-L39" }, { "kind": "response", @@ -222385,7 +222435,7 @@ "body": { "kind": "no_body" }, - "description": "Get Watcher statistics.", + "description": "Get Watcher statistics.\nThis API always returns basic metrics.\nYou retrieve more metrics by using the metric parameter.", "inherits": { "type": { "name": "RequestBase", @@ -222467,7 +222517,7 @@ } } ], - "specLocation": "watcher/stats/WatcherStatsRequest.ts#L23-L47" + "specLocation": "watcher/stats/WatcherStatsRequest.ts#L23-L50" }, { "kind": "response", @@ -222538,6 +222588,7 @@ }, "properties": [ { + "description": "The time the watch was run.\nThis is just before the input is being run.", "name": "execution_time", "required": true, "type": { @@ -222549,7 +222600,7 @@ } } ], - "specLocation": "watcher/stats/types.ts#L50-L52" + "specLocation": "watcher/stats/types.ts#L71-L77" }, { "kind": "interface", @@ -222565,6 +222616,7 @@ }, "properties": [ { + "description": "The current watch execution phase.", "name": "execution_phase", "required": true, "type": { @@ -222576,6 +222628,7 @@ } }, { + "description": "The time the watch was triggered by the trigger engine.", "name": "triggered_time", "required": true, "type": { @@ -222612,6 +222665,7 @@ } }, { + "description": "The watch record identifier.", "name": "watch_record_id", "required": true, "type": { @@ -222623,7 +222677,7 @@ } } ], - "specLocation": "watcher/stats/types.ts#L54-L60" + "specLocation": "watcher/stats/types.ts#L79-L94" }, { "kind": "enum", @@ -222648,7 +222702,7 @@ "name": "WatcherMetric", "namespace": "watcher.stats" }, - "specLocation": "watcher/stats/types.ts#L42-L48" + "specLocation": "watcher/stats/types.ts#L63-L69" }, { "kind": "interface", @@ -222658,6 +222712,7 @@ }, "properties": [ { + "description": "The current executing watches metric gives insight into the watches that are currently being executed by Watcher.\nAdditional information is shared per watch that is currently executing.\nThis information includes the `watch_id`, the time its execution started and its current execution phase.\nTo include this metric, the `metric` option should be set to `current_watches` or `_all`.\nIn addition you can also specify the `emit_stacktraces=true` parameter, which adds stack traces for each watch that is being run.\nThese stack traces can give you more insight into an execution of a watch.", "name": "current_watches", "required": false, "type": { @@ -222683,6 +222738,7 @@ } }, { + "description": "Watcher moderates the execution of watches such that their execution won't put too much pressure on the node and its resources.\nIf too many watches trigger concurrently and there isn't enough capacity to run them all, some of the watches are queued, waiting for the current running watches to finish.s\nThe queued watches metric gives insight on these queued watches.\n\nTo include this metric, the `metric` option should include `queued_watches` or `_all`.", "name": "queued_watches", "required": false, "type": { @@ -222697,6 +222753,7 @@ } }, { + "description": "The number of watches currently registered.", "name": "watch_count", "required": true, "type": { @@ -222708,6 +222765,7 @@ } }, { + "description": "The current state of Watcher.", "name": "watcher_state", "required": true, "type": { @@ -222730,7 +222788,7 @@ } } ], - "specLocation": "watcher/stats/types.ts#L33-L40" + "specLocation": "watcher/stats/types.ts#L33-L61" }, { "kind": "enum", @@ -222776,7 +222834,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -222789,7 +222847,7 @@ } } ], - "specLocation": "watcher/stop/WatcherStopRequest.ts#L23-L38" + "specLocation": "watcher/stop/WatcherStopRequest.ts#L23-L41" }, { "kind": "response", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index aa2f6454bd..f6e76e62e6 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -21109,7 +21109,8 @@ export interface WatcherPutWatchRequest extends RequestBase { condition?: WatcherConditionContainer input?: WatcherInputContainer metadata?: Metadata - throttle_period?: string + throttle_period?: Duration + throttle_period_in_millis?: DurationValue transform?: TransformContainer trigger?: WatcherTriggerContainer } diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 67196e7686..b4a9703f97 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -504,6 +504,7 @@ run-as-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch runtime-search-request,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results +search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html search-aggregations-bucket-adjacency-matrix-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-adjacency-matrix-aggregation.html search-aggregations-bucket-autodatehistogram-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-autodatehistogram-aggregation.html diff --git a/specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml b/specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml index 2a61a48461..1baa3e6d98 100644 --- a/specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml +++ b/specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml @@ -3,4 +3,4 @@ description: A successful response for creating an auto-follow pattern. # type: response # response_code: 200 value: - acknowledged": true + acknowledged: true diff --git a/specification/watcher/_types/Execution.ts b/specification/watcher/_types/Execution.ts index 2a134ac7c4..0517b4e880 100644 --- a/specification/watcher/_types/Execution.ts +++ b/specification/watcher/_types/Execution.ts @@ -92,6 +92,12 @@ export class ExecutionResultInput { } export class ExecutionThreadPool { + /** + * The largest size of the execution thread pool, which indicates the largest number of concurrent running watches. + */ max_size: long + /** + * The number of watches that were triggered and are currently queued. + */ queue_size: long } diff --git a/specification/watcher/ack_watch/WatcherAckWatchRequest.ts b/specification/watcher/ack_watch/WatcherAckWatchRequest.ts index 39dddff31a..a276090f67 100644 --- a/specification/watcher/ack_watch/WatcherAckWatchRequest.ts +++ b/specification/watcher/ack_watch/WatcherAckWatchRequest.ts @@ -28,13 +28,24 @@ import { Name, Names } from '@_types/common' * * IMPORTANT: If the specified watch is currently being executed, this API will return an error * The reason for this behavior is to prevent overwriting the watch status from a watch execution. + * + * 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). * @rest_spec_name watcher.ack_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-ack-watch */ export interface Request extends RequestBase { path_parts: { + /** + * The watch identifier. + */ watch_id: Name + /** + * A comma-separated list of the action identifiers to acknowledge. + * If you omit this parameter, all of the actions of the watch are acknowledged. + */ action_id?: Names } } diff --git a/specification/watcher/ack_watch/examples/response/WatcherAckWatchResponseExample1.yaml b/specification/watcher/ack_watch/examples/response/WatcherAckWatchResponseExample1.yaml new file mode 100644 index 0000000000..09848ed691 --- /dev/null +++ b/specification/watcher/ack_watch/examples/response/WatcherAckWatchResponseExample1.yaml @@ -0,0 +1,33 @@ +# summary: +description: A successful response from `POST _watcher/watch/my_watch/_ack`. +# type: response +# response_code: 200 +value: |- + { + "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 + } + } diff --git a/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts b/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts index 4a491a2c2d..4a48cec2f3 100644 --- a/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts +++ b/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts @@ -26,10 +26,14 @@ import { Name } from '@_types/common' * @rest_spec_name watcher.activate_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-activate-watch * @ext_doc_id watcher-works */ export interface Request extends RequestBase { path_parts: { + /** + * The watch identifier. + */ watch_id: Name } } diff --git a/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts b/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts index 1c00ea404f..a4675d69fc 100644 --- a/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts +++ b/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts @@ -26,10 +26,14 @@ import { Name } from '@_types/common' * @rest_spec_name watcher.deactivate_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-deactivate-watch * @ext_doc_id watcher-works */ export interface Request extends RequestBase { path_parts: { + /** + * The watch identifier. + */ watch_id: Name } } diff --git a/specification/watcher/delete_watch/DeleteWatchRequest.ts b/specification/watcher/delete_watch/DeleteWatchRequest.ts index dcc63e757e..ca115f6005 100644 --- a/specification/watcher/delete_watch/DeleteWatchRequest.ts +++ b/specification/watcher/delete_watch/DeleteWatchRequest.ts @@ -32,9 +32,13 @@ import { Name } from '@_types/common' * @rest_spec_name watcher.delete_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-delete-watch */ export interface Request extends RequestBase { path_parts: { + /** + * The watch identifier. + */ id: Name } } diff --git a/specification/watcher/delete_watch/examples/response/DeleteWatchResponseExample1.yaml b/specification/watcher/delete_watch/examples/response/DeleteWatchResponseExample1.yaml new file mode 100644 index 0000000000..e3c46417f4 --- /dev/null +++ b/specification/watcher/delete_watch/examples/response/DeleteWatchResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: +description: A successful response from `DELETE _watcher/watch/my_watch`. +# type: response +# response_code: 200 +value: |- + { + "found": true, + "_id": "my_watch", + "_version": 2 + } diff --git a/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts b/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts index 40d5ae3422..9c9d00a5df 100644 --- a/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts +++ b/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts @@ -35,14 +35,20 @@ import { Id } from '@_types/common' * * You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. * This serves as great tool for testing and debugging your watches prior to adding them to Watcher. + * + * When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. + * If your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch. + * + * When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch. * @rest_spec_name watcher.execute_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-execute-watch */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the watch. + * The watch identifier. */ id?: Id } @@ -68,17 +74,20 @@ export interface Request extends RequestBase { */ ignore_condition?: boolean /** - * When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent executions. This can also be specified as an HTTP parameter. + * When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. + * In addition, the status of the watch is updated, possibly throttling subsequent runs. + * This can also be specified as an HTTP parameter. * @server_default false */ record_execution?: boolean simulated_actions?: SimulatedActions /** - * This structure is parsed as the data of the trigger event that will be used during the watch execution + * This structure is parsed as the data of the trigger event that will be used during the watch execution. */ trigger_data?: ScheduleTriggerEvent /** - * When present, this 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. + * When present, this 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. * @server_default null */ watch?: Watch diff --git a/specification/watcher/execute_watch/WatcherExecuteWatchResponse.ts b/specification/watcher/execute_watch/WatcherExecuteWatchResponse.ts index f383b77573..de76a72aba 100644 --- a/specification/watcher/execute_watch/WatcherExecuteWatchResponse.ts +++ b/specification/watcher/execute_watch/WatcherExecuteWatchResponse.ts @@ -21,5 +21,14 @@ import { Id } from '@_types/common' import { WatchRecord } from './types' export class Response { - body: { _id: Id; watch_record: WatchRecord } + body: { + /** + * The watch record identifier as it would be stored in the `.watcher-history` index. + */ + _id: Id + /** + * The watch record document as it would be stored in the `.watcher-history` index. + */ + watch_record: WatchRecord + } } diff --git a/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample1.yaml b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample1.yaml new file mode 100644 index 0000000000..bdc0ed3681 --- /dev/null +++ b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample1.yaml @@ -0,0 +1,24 @@ +summary: Run a watch +# method_request: POST _watcher/watch/my_watch/_execute +description: > + Run `POST _watcher/watch/my_watch/_execute` to run a watch. + The input defined in the watch is ignored and the `alternative_input` is used as the payload. + The condition as defined by the watch is ignored and is assumed to evaluate to true. + The `force_simulate` action forces the simulation of `my-action`. + Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally. +# type: request +value: |- + { + "trigger_data" : { + "triggered_time" : "now", + "scheduled_time" : "now" + }, + "alternative_input" : { + "foo" : "bar" + }, + "ignore_condition" : true, + "action_modes" : { + "my-action" : "force_simulate" + }, + "record_execution" : true + } diff --git a/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample2.yaml b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample2.yaml new file mode 100644 index 0000000000..716d889396 --- /dev/null +++ b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample2.yaml @@ -0,0 +1,12 @@ +summary: Run a watch with multiple action modes +# method_request: POST _watcher/watch/my_watch/_execute +description: > + Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action. +# type: request +value: |- + { + "action_modes" : { + "action1" : "force_simulate", + "action2" : "skip" + } + } diff --git a/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample3.yaml b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample3.yaml new file mode 100644 index 0000000000..fd162c8eff --- /dev/null +++ b/specification/watcher/execute_watch/examples/request/WatcherExecuteRequestExample3.yaml @@ -0,0 +1,35 @@ +summary: Run a watch inline +# method_request: POST _watcher/watch/_execute +description: > + Run `POST _watcher/watch/_execute` to run a watch inline. + All other settings for this API still apply when inlining a watch. + In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored. +# type: request +value: |- + { + "watch" : { + "trigger" : { "schedule" : { "interval" : "10s" } }, + "input" : { + "search" : { + "request" : { + "indices" : [ "logs" ], + "body" : { + "query" : { + "match" : { "message": "error" } + } + } + } + } + }, + "condition" : { + "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }} + }, + "actions" : { + "log_error" : { + "logging" : { + "text" : "Found {{ctx.payload.hits.total}} errors in the logs" + } + } + } + } + } diff --git a/specification/watcher/execute_watch/examples/response/WatcherExecuteWatchResponseExample1.yaml b/specification/watcher/execute_watch/examples/response/WatcherExecuteWatchResponseExample1.yaml new file mode 100644 index 0000000000..7e6c6a2db2 --- /dev/null +++ b/specification/watcher/execute_watch/examples/response/WatcherExecuteWatchResponseExample1.yaml @@ -0,0 +1,94 @@ +# summary: +description: > + A successful response from `POST _watcher/watch/my_watch/_execute`. +# type: response +# response_code: 200 +value: |- + { + "_id": "my_watch_0-2015-06-02T23:17:55.124Z", + "watch_record": { + "@timestamp": "2015-06-02T23:17:55.124Z", + "watch_id": "my_watch", + "node": "my_node", + "messages": [], + "trigger_event": { + "type": "manual", + "triggered_time": "2015-06-02T23:17:55.124Z", + "manual": { + "schedule": { + "scheduled_time": "2015-06-02T23:17:55.124Z" + } + } + }, + "state": "executed", + "status": { + "version": 1, + "execution_state": "executed", + "state": { + "active": true, + "timestamp": "2015-06-02T23:17:55.111Z" + }, + "last_checked": "2015-06-02T23:17:55.124Z", + "last_met_condition": "2015-06-02T23:17:55.124Z", + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-06-02T23:17:55.124Z", + "state": "ackable" + }, + "last_execution": { + "timestamp": "2015-06-02T23:17:55.124Z", + "successful": true + }, + "last_successful_execution": { + "timestamp": "2015-06-02T23:17:55.124Z", + "successful": true + } + } + } + }, + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "result": { + "execution_time": "2015-06-02T23:17:55.124Z", + "execution_duration": 12608, + "input": { + "type": "simple", + "payload": { + "foo": "bar" + }, + "status": "success" + }, + "condition": { + "type": "always", + "met": true, + "status": "success" + }, + "actions": [ + { + "id": "test_index", + "index": { + "response": { + "index": "test", + "version": 1, + "created": true, + "result": "created", + "id": "AVSHKzPa9zx62AzUzFXY" + } + }, + "status": "success", + "type": "index" + } + ] + }, + "user": "test_admin" + } + } diff --git a/specification/watcher/get_watch/GetWatchRequest.ts b/specification/watcher/get_watch/GetWatchRequest.ts index c6acb64013..4a7d876123 100644 --- a/specification/watcher/get_watch/GetWatchRequest.ts +++ b/specification/watcher/get_watch/GetWatchRequest.ts @@ -25,9 +25,13 @@ import { Name } from '@_types/common' * @rest_spec_name watcher.get_watch * @availability stack since=5.6.0 stability=stable * @cluster_privileges monitor_watcher + * @doc_id watcher-api-get-watch */ export interface Request extends RequestBase { path_parts: { + /** + * The watch identifier. + */ id: Name } } diff --git a/specification/watcher/get_watch/examples/response/GetWatchResponseExample1.yaml b/specification/watcher/get_watch/examples/response/GetWatchResponseExample1.yaml new file mode 100644 index 0000000000..658da6e193 --- /dev/null +++ b/specification/watcher/get_watch/examples/response/GetWatchResponseExample1.yaml @@ -0,0 +1,53 @@ +# summary: +description: A successful response from `GET _watcher/watch/my_watch`. +# type: response +# response_code: 200 +value: |- + { + "found": true, + "_id": "my_watch", + "_seq_no": 0, + "_primary_term": 1, + "_version": 1, + "status": { + "version": 1, + "state": { + "active": true, + "timestamp": "2015-05-26T18:21:08.630Z" + }, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:21:08.630Z", + "state": "awaits_successful_execution" + } + } + } + }, + "watch": { + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "trigger": { + "schedule": { + "hourly": { + "minute": [0, 5] + } + } + }, + "actions": { + "test_index": { + "index": { + "index": "test" + } + } + } + } + } diff --git a/specification/watcher/put_watch/WatcherPutWatchRequest.ts b/specification/watcher/put_watch/WatcherPutWatchRequest.ts index c5f474e0f7..16cb813600 100644 --- a/specification/watcher/put_watch/WatcherPutWatchRequest.ts +++ b/specification/watcher/put_watch/WatcherPutWatchRequest.ts @@ -25,6 +25,7 @@ import { TriggerContainer } from '@watcher/_types/Trigger' import { RequestBase } from '@_types/Base' import { Id, Metadata, SequenceNumber, VersionNumber } from '@_types/common' import { long } from '@_types/Numeric' +import { Duration, DurationValue, UnitMillis } from '@_types/Time' import { TransformContainer } from '@_types/Transform' /** @@ -43,24 +44,61 @@ import { TransformContainer } from '@_types/Transform' * @rest_spec_name watcher.put_watch * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-put-watch */ export interface Request extends RequestBase { path_parts: { + /** + * The identifier for the watch. + */ id: Id } query_parameters: { + /** + * The initial state of the watch. + * The default value is `true`, which means the watch is active by default. + * @server_default true + */ active?: boolean if_primary_term?: long if_seq_no?: SequenceNumber version?: VersionNumber } body: { + /** + * The list of actions that will be run if the condition matches. + */ actions?: Dictionary + /** + * The condition that defines if the actions should be run. + */ condition?: ConditionContainer + /** + * The input that defines the input that loads the data for the watch. + */ input?: InputContainer + /** + * Metadata JSON that will be copied into the history entries. + */ metadata?: Metadata - throttle_period?: string + /** + * The minimum time between actions being run. + * The default is 5 seconds. + * This default can be changed in the config file with the setting `xpack.watcher.throttle.period.default_period`. + * If both this value and the `throttle_period_in_millis` parameter are specified, Watcher uses the last parameter included in the request. + */ + throttle_period?: Duration + /** + * Minimum time in milliseconds between actions being run. Defaults to 5000. If both this value and the throttle_period parameter are specified, Watcher uses the last parameter included in the request. + */ + throttle_period_in_millis?: DurationValue + /** + * The transform that processes the watch payload to prepare it for the watch actions. + */ transform?: TransformContainer + /** + * The trigger that defines when the watch should run. + */ trigger?: TriggerContainer } } diff --git a/specification/watcher/put_watch/examples/request/WatcherPutWatchRequestExample1.yaml b/specification/watcher/put_watch/examples/request/WatcherPutWatchRequestExample1.yaml new file mode 100644 index 0000000000..54e1540124 --- /dev/null +++ b/specification/watcher/put_watch/examples/request/WatcherPutWatchRequestExample1.yaml @@ -0,0 +1,54 @@ +# summary: +# method_request: PUT _watcher/watch/my-watch +description: > + Run `PUT _watcher/watch/my-watch` add a watch. + The watch schedule triggers every minute. + The watch search input looks for any 404 HTTP responses that occurred in the last five minutes. + The watch condition checks if any search hits where found. + When found, the watch action sends an email to an administrator. +# type: request +value: |- + { + "trigger" : { + "schedule" : { "cron" : "0 0/1 * * * ?" } + }, + "input" : { + "search" : { + "request" : { + "indices" : [ + "logstash*" + ], + "body" : { + "query" : { + "bool" : { + "must" : { + "match": { + "response": 404 + } + }, + "filter" : { + "range": { + "@timestamp": { + "from": "{{ctx.trigger.scheduled_time}}||-5m", + "to": "{{ctx.trigger.triggered_time}}" + } + } + } + } + } + } + } + } + }, + "condition" : { + "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }} + }, + "actions" : { + "email_admin" : { + "email" : { + "to" : "admin@domain.host.com", + "subject" : "404 recently encountered" + } + } + } + } diff --git a/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts b/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts index 75c6880b6f..5cd3aed8fe 100644 --- a/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts +++ b/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts @@ -25,27 +25,40 @@ import { Sort, SortResults } from '@_types/sort' /** * Query watches. * Get all registered watches in a paginated manner and optionally filter watches by a query. + * + * Note that only the `_id` and `metadata.*` fields are queryable or sortable. * @rest_spec_name watcher.query_watches * @availability stack since=7.11.0 stability=stable * @cluster_privileges monitor_watcher + * @doc_id watcher-api-query-watches */ export interface Request extends RequestBase { body: { /** - * The offset from the first result to fetch. Needs to be non-negative. + * The offset from the first result to fetch. + * It must be non-negative. * @server_default 0 */ from?: integer /** - * The number of hits to return. Needs to be non-negative. + * The number of hits to return. + * It must be non-negative. * @server_default 10 */ size?: integer - /** Optional, query filter watches to be returned. */ + /** + * A query that filters the watches to be returned. + */ query?: QueryContainer - /** Optional sort definition. */ + /** + * One or more fields used to sort the search results. + * @ext_doc_id sort-search-results + */ sort?: Sort - /** Optional search After to do pagination using last hit’s sort values. */ + /** + * Retrieve the next page of hits using a set of sort values from the previous page. + * @ext_doc_id search-after + */ search_after?: SortResults } } diff --git a/specification/watcher/query_watches/WatcherQueryWatchesResponse.ts b/specification/watcher/query_watches/WatcherQueryWatchesResponse.ts index 228b7ae2c3..d238034d02 100644 --- a/specification/watcher/query_watches/WatcherQueryWatchesResponse.ts +++ b/specification/watcher/query_watches/WatcherQueryWatchesResponse.ts @@ -22,7 +22,13 @@ import { QueryWatch } from '../_types/Watch' export class Response { body: { + /** + * The total number of watches found. + */ count: integer + /** + * A list of watches based on the `from`, `size`, or `search_after` request body parameters. + */ watches: QueryWatch[] } } diff --git a/specification/watcher/query_watches/examples/response/WatcherQueryWatchesResponseExample1.yaml b/specification/watcher/query_watches/examples/response/WatcherQueryWatchesResponseExample1.yaml new file mode 100644 index 0000000000..d60a187ba9 --- /dev/null +++ b/specification/watcher/query_watches/examples/response/WatcherQueryWatchesResponseExample1.yaml @@ -0,0 +1,59 @@ +# summary: '' +description: A successful response from `GET /_watcher/_query/watches`. +# type: response +# response_code: 200 +value: |- + { + "count": 1, + "watches": [ + { + "_id": "my_watch", + "watch": { + "trigger": { + "schedule": { + "hourly": { + "minute": [ + 0, + 5 + ] + } + } + }, + "input": { + "simple": { + "payload": { + "send": "yes" + } + } + }, + "condition": { + "always": {} + }, + "actions": { + "test_index": { + "index": { + "index": "test" + } + } + } + }, + "status": { + "state": { + "active": true, + "timestamp": "2015-05-26T18:21:08.630Z" + }, + "actions": { + "test_index": { + "ack": { + "timestamp": "2015-05-26T18:21:08.630Z", + "state": "awaits_successful_execution" + } + } + }, + "version": -1 + }, + "_seq_no": 0, + "_primary_term": 1 + } + ] + } diff --git a/specification/watcher/start/WatcherStartRequest.ts b/specification/watcher/start/WatcherStartRequest.ts index 63e2a6d0c0..bd488ef055 100644 --- a/specification/watcher/start/WatcherStartRequest.ts +++ b/specification/watcher/start/WatcherStartRequest.ts @@ -26,6 +26,7 @@ import { Duration } from '@_types/Time' * @rest_spec_name watcher.start * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-start */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/watcher/start/examples/response/WatcherStartResponseExample1.yaml b/specification/watcher/start/examples/response/WatcherStartResponseExample1.yaml new file mode 100644 index 0000000000..1808a96b58 --- /dev/null +++ b/specification/watcher/start/examples/response/WatcherStartResponseExample1.yaml @@ -0,0 +1,6 @@ +# summary: '' +description: A successful response from `POST _watcher/_start`. +# type: response +# response_code: 200 +value: + acknowledged: true diff --git a/specification/watcher/stats/WatcherStatsRequest.ts b/specification/watcher/stats/WatcherStatsRequest.ts index b13be11185..4ce4dcd4a2 100644 --- a/specification/watcher/stats/WatcherStatsRequest.ts +++ b/specification/watcher/stats/WatcherStatsRequest.ts @@ -22,9 +22,12 @@ import { WatcherMetric } from './types' /** * Get Watcher statistics. + * This API always returns basic metrics. + * You retrieve more metrics by using the metric parameter. * @rest_spec_name watcher.stats * @availability stack since=5.5.0 stability=stable * @cluster_privileges monitor_watcher + * @doc_id watcher-api-stats */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/watcher/stats/examples/response/WatcherStatsResponseExample1.yaml b/specification/watcher/stats/examples/response/WatcherStatsResponseExample1.yaml new file mode 100644 index 0000000000..779bb81fff --- /dev/null +++ b/specification/watcher/stats/examples/response/WatcherStatsResponseExample1.yaml @@ -0,0 +1,13 @@ +summary: Basic metrics +description: A successful response from `GET _watcher/stats`. +# type: response +# response_code: 200 +value: |- + { + "watcher_state": "started", + "watch_count": 1, + "execution_thread_pool": { + "size": 1000, + "max_size": 1 + } + } diff --git a/specification/watcher/stats/examples/response/WatcherStatsResponseExample2.yaml b/specification/watcher/stats/examples/response/WatcherStatsResponseExample2.yaml new file mode 100644 index 0000000000..6cf5a4983d --- /dev/null +++ b/specification/watcher/stats/examples/response/WatcherStatsResponseExample2.yaml @@ -0,0 +1,22 @@ +summary: Current watch metrics +description: A successful response from `GET _watcher/stats?metric=current_watches`. +# type: response +# response_code: 200 +value: |- + { + "watcher_state": "started", + "watch_count": 2, + "execution_thread_pool": { + "queue_size": 1000, + "max_size": 20 + }, + "current_watches": [ + { + "watch_id": "slow_condition", + "watch_record_id": "slow_condition_3-2015-05-13T07:42:32.179Z", + "triggered_time": "2015-05-12T11:53:51.800Z", + "execution_time": "2015-05-13T07:42:32.179Z", + "execution_phase": "condition" + } + ] + } diff --git a/specification/watcher/stats/examples/response/WatcherStatsResponseExample3.yaml b/specification/watcher/stats/examples/response/WatcherStatsResponseExample3.yaml new file mode 100644 index 0000000000..374b90e9fe --- /dev/null +++ b/specification/watcher/stats/examples/response/WatcherStatsResponseExample3.yaml @@ -0,0 +1,21 @@ +summary: Queued watch metrics +description: An abbreviated response from `GET _watcher/stats/queued_watches`. +# type: response +# response_code: 200 +value: |- + { + "watcher_state": "started", + "watch_count": 10, + "execution_thread_pool": { + "queue_size": 1000, + "max_size": 20 + }, + "queued_watches": [ + { + "watch_id": "slow_condition4", + "watch_record_id": "slow_condition4_223-2015-05-21T11:59:59.811Z", + "triggered_time": "2015-05-21T11:59:59.811Z", + "execution_time": "2015-05-21T11:59:59.811Z" + } + ] + } diff --git a/specification/watcher/stats/types.ts b/specification/watcher/stats/types.ts index 64ee510015..67ac9fc280 100644 --- a/specification/watcher/stats/types.ts +++ b/specification/watcher/stats/types.ts @@ -31,10 +31,31 @@ export enum WatcherState { } export class WatcherNodeStats { + /** + * The current executing watches metric gives insight into the watches that are currently being executed by Watcher. + * Additional information is shared per watch that is currently executing. + * This information includes the `watch_id`, the time its execution started and its current execution phase. + * To include this metric, the `metric` option should be set to `current_watches` or `_all`. + * In addition you can also specify the `emit_stacktraces=true` parameter, which adds stack traces for each watch that is being run. + * These stack traces can give you more insight into an execution of a watch. + */ current_watches?: WatchRecordStats[] execution_thread_pool: ExecutionThreadPool + /** + * Watcher moderates the execution of watches such that their execution won't put too much pressure on the node and its resources. + * If too many watches trigger concurrently and there isn't enough capacity to run them all, some of the watches are queued, waiting for the current running watches to finish.s + * The queued watches metric gives insight on these queued watches. + * + * To include this metric, the `metric` option should include `queued_watches` or `_all`. + */ queued_watches?: WatchRecordQueuedStats[] + /** + * The number of watches currently registered. + */ watch_count: long + /** + * The current state of Watcher. + */ watcher_state: WatcherState node_id: Id } @@ -48,13 +69,26 @@ export enum WatcherMetric { } export class WatchRecordQueuedStats { + /** + * The time the watch was run. + * This is just before the input is being run. + */ execution_time: DateTime } export class WatchRecordStats extends WatchRecordQueuedStats { + /** + * The current watch execution phase. + */ execution_phase: ExecutionPhase + /** + * The time the watch was triggered by the trigger engine. + */ triggered_time: DateTime executed_actions?: Array watch_id: Id + /** + * The watch record identifier. + */ watch_record_id: Id } diff --git a/specification/watcher/stop/WatcherStopRequest.ts b/specification/watcher/stop/WatcherStopRequest.ts index ba8d031c36..5d00e7c7c5 100644 --- a/specification/watcher/stop/WatcherStopRequest.ts +++ b/specification/watcher/stop/WatcherStopRequest.ts @@ -26,11 +26,14 @@ import { Duration } from '@_types/Time' * @rest_spec_name watcher.stop * @availability stack stability=stable * @cluster_privileges manage_watcher + * @doc_id watcher-api-stop */ export interface Request extends RequestBase { query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/watcher/stop/examples/response/WatcherStopResponseExample1.yaml b/specification/watcher/stop/examples/response/WatcherStopResponseExample1.yaml new file mode 100644 index 0000000000..175b2942ca --- /dev/null +++ b/specification/watcher/stop/examples/response/WatcherStopResponseExample1.yaml @@ -0,0 +1,6 @@ +# summary: '' +description: A successful response from `POST _watcher/_stop`. +# type: response +# response_code: 200 +value: + acknowledged: true