195 lines
6.6 KiB
Plaintext
195 lines
6.6 KiB
Plaintext
[role="xpack"]
|
|
[[watcher-api-stats]]
|
|
=== Get {watcher} stats API
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Get {watcher} stats</titleabbrev>
|
|
++++
|
|
|
|
Retrieves the current {watcher} metrics.
|
|
|
|
[[watcher-api-stats-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET _watcher/stats` +
|
|
|
|
`GET _watcher/stats/<metric>`
|
|
|
|
[[watcher-api-stats-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
|
|
this API. For more information, see
|
|
{stack-ov}/security-privileges.html[Security privileges].
|
|
|
|
//[[watcher-api-stats-desc]]
|
|
//==== {api-description-title}
|
|
|
|
[[watcher-api-stats-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`emit_stacktraces`::
|
|
(Optional, boolean) Defines whether stack traces are generated for each watch
|
|
that is running. The default value is `false`.
|
|
|
|
`<metric>`::
|
|
(Optional, enum) Defines which additional metrics are included in the response.
|
|
`current_watches`::: Includes the current executing watches in the response.
|
|
`queued_watches`::: Includes the watches queued for execution in the response.
|
|
`_all`::: Includes all metrics in the response.
|
|
|
|
//[[watcher-api-stats-query-params]]
|
|
//==== {api-query-parms-title}
|
|
|
|
//[[watcher-api-stats-request-body]]
|
|
//==== {api-request-body-title}
|
|
|
|
[[watcher-api-stats-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
This API always returns basic metrics. You retrieve more metrics by using
|
|
the `metric` parameter.
|
|
|
|
`current_watches`::
|
|
(list) 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 executed. These
|
|
stack traces can give you more insight into an execution of a watch.
|
|
|
|
`queued_watches`::
|
|
(list) {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 execute them all, some
|
|
of the watches are queued, waiting for the current executing watches to finish
|
|
their execution. The queued watches metric gives insight on these queued
|
|
watches.
|
|
|
|
To include this metric, the `metric` option should include `queued_watches` or
|
|
`_all`.
|
|
|
|
//[[watcher-api-stats-response-codes]]
|
|
//==== {api-response-codes-title}
|
|
|
|
[[watcher-api-stats-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example calls the `stats` API to retrieve basic metrics:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/stats
|
|
--------------------------------------------------
|
|
|
|
A successful call returns a JSON structure similar to the following example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"watcher_state": "started", <1>
|
|
"watch_count": 1, <2>
|
|
"execution_thread_pool": {
|
|
"size": 1000, <3>
|
|
"max_size": 1 <4>
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> The current state of watcher, which can be `started`, `starting`, or `stopped`.
|
|
<2> The number of watches currently registered.
|
|
<3> The number of watches that were triggered and currently queued for execution.
|
|
<4> The largest size of the execution thread pool, which indicates the largest
|
|
number of concurrent executing watches.
|
|
|
|
The following example specifies the `metric` option as a query string argument
|
|
and will include the basic metrics and metrics about the current executing watches:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/stats?metric=current_watches
|
|
--------------------------------------------------
|
|
|
|
The following example specifies the `metric` option as part of the url path:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/stats/current_watches
|
|
--------------------------------------------------
|
|
|
|
The following snippet shows an example of a successful JSON response that
|
|
captures a watch in execution:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"watcher_state": "started",
|
|
"watch_count": 2,
|
|
"execution_thread_pool": {
|
|
"queue_size": 1000,
|
|
"max_size": 20
|
|
},
|
|
"current_watches": [ <1>
|
|
{
|
|
"watch_id": "slow_condition", <2>
|
|
"watch_record_id": "slow_condition_3-2015-05-13T07:42:32.179Z", <3>
|
|
"triggered_time": "2015-05-12T11:53:51.800Z", <4>
|
|
"execution_time": "2015-05-13T07:42:32.179Z", <5>
|
|
"execution_phase": "condition" <6>
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> A list of all the watches that are currently being executed by {watcher}.
|
|
When no watches are currently executing, an empty array is returned. The
|
|
captured watches are sorted by execution time in descending order. Thus the
|
|
longest running watch is always at the top.
|
|
<2> The id of the watch being executed.
|
|
<3> The id of the watch record.
|
|
<4> The time the watch was triggered by the trigger engine.
|
|
<5> The time the watch was executed. This is just before the input is being
|
|
executed.
|
|
<6> The current watch execution phase. Can be `input`, `condition` `actions`,
|
|
`awaits_execution`, `started`, `watch_transform`, `aborted`, `finished`.
|
|
|
|
The following example specifies the `queued_watches` metric option and includes
|
|
both the basic metrics and the queued watches:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/stats/queued_watches
|
|
--------------------------------------------------
|
|
|
|
An example of a successful JSON response that captures a watch in execution:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"watcher_state": "started",
|
|
"watch_count": 10,
|
|
"execution_thread_pool": {
|
|
"queue_size": 1000,
|
|
"max_size": 20
|
|
},
|
|
"queued_watches": [ <1>
|
|
{
|
|
"watch_id": "slow_condition4", <2>
|
|
"watch_record_id": "slow_condition4_223-2015-05-21T11:59:59.811Z", <3>
|
|
"triggered_time": "2015-05-21T11:59:59.811Z", <4>
|
|
"execution_time": "2015-05-21T11:59:59.811Z" <5>
|
|
},
|
|
...
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
<1> A list of all watches that are currently queued for execution. When no
|
|
watches are queued, an empty array is returned.
|
|
<2> The id of the watch queued for execution.
|
|
<3> The id of the watch record.
|
|
<4> The time the watch was triggered by the trigger engine.
|
|
<5> The time the watch was went into a queued state.
|