OpenSearch/watcher/docs/reference/rest/stats.asciidoc

[[api-rest-stats]]
==== Stats API

The watcher `stats` API returns information on the aspects of watcher on your cluster.

The watcher `stats` API supports the following request options

[options="header"]
|======
| Name               | Required | Default | Description
| metric             | no       | null    | What metric should be returned.
|======

The supported metric values:

[options="header"]
|======
| Metric             | Description
| executing_watches  | Include the current executing watches in the response.
| queued_watches     | Include the watches queued for execution in the response.
| _all               | Include all metrics in the response.
|======

The watcher `stats` API always returns basic metrics regardless of the `metric` option.

The following example queries the `stats` API including the basic metrics:

[source,js]
--------------------------------------------------
GET _watcher/stats
--------------------------------------------------
// AUTOSENSE

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. May be either `started`, `starting` or `stopped`.
<2> The number of watches currently registered in watcher.
<3> The number of watches that were triggered and currently queued for execution.
<4> The largest size of the execution thread pool indicating the largest number of concurrent executing watches.

===== Current executing watches metric

The current executing watches metric gives insight into the watches that are currently being executed by Watcher.
Per watch that is executing information is shared, like the `watch_id`, when execution started and at what phase the
execution is.

To include this metric, the `metric` option should be set to `executing_watches` or `_all`.

The following example specifies the `metric` option as a query string argument and will include the basic metrics and
metrics about the current watches being executed:

[source,js]
--------------------------------------------------
GET _watcher/stats?metric=executing_watches
--------------------------------------------------
// AUTOSENSE

The following example specifies the `metric` option as part of the url path:

[source,js]
--------------------------------------------------
GET _watcher/stats/current_watches
--------------------------------------------------
// AUTOSENSE

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. In case of an empty array no executing watches
    had been captured. The captured watches are sorted by execution time in descending order. So the longest running watch
    is always on 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 execution phase the watch is in. Can be `input`, `condition` or `action`.

===== Queued watches metric

When a watch triggers it is being prepared for execution and when there is capacity the watch get executed.
If many watches trigger concurrently and there is no capacity to execute then watches are queued up. These watches
are then queued for execution. The queued watches metric gives insight what watches are queued for execution.

To include this metric, the `metric` option should include `queued_watches` or `_all`.

The following example specifies the `queued_watches` metric option and will include the basic metrics and
the watches queued for execution:

[source,js]
--------------------------------------------------
GET _watcher/stats/queued_watches
--------------------------------------------------
// AUTOSENSE

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 the Watches that are queued for execution. In case of an empty array no watches are queued for execution.
<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.