OpenSearch/x-pack/docs/en/rest-api/watcher/stats.asciidoc

[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
<<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.