diff --git a/docs/reference/cat/thread_pool.asciidoc b/docs/reference/cat/thread_pool.asciidoc index 5440bc4e3ac..cea2b5e4d49 100644 --- a/docs/reference/cat/thread_pool.asciidoc +++ b/docs/reference/cat/thread_pool.asciidoc @@ -1,8 +1,119 @@ [[cat-thread-pool]] === cat thread pool -The `thread_pool` command shows cluster wide thread pool statistics per node. By default the active, queue and rejected -statistics are returned for all thread pools. +Returns thread pool statistics for each node in a cluster. Returned information +includes all <> and custom thread +pools. + + +[[cat-thread-pool-api-request]] +==== {api-request-title} + +`GET /_cat/thread_pool/{thread_pool}` + +[[cat-thread-pool-path-params]] +==== {api-path-parms-title} + +`{thread_pool}`:: +(Optional, string) Comma-separated list of thread pool names used to limit the +request. Accepts wildcard expressions. + + +[[cat-thread-pool-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h] ++ +-- +If you do not specify which columns to include, the API returns the default +columns in the order listed below. If you explicitly specify one or more +columns, it only returns the specified columns. + +Valid columns are: + +`node_name`:: +(Default) Node name, such as `I8hydUG`. + +`name`:: +(Default) Name of the thread pool, such as `analyze` or `generic`. + +`active`, `a`:: +(Default) Number of active threads in the current thread pool. + +`queue`,`q`:: +(Default) Number of tasks in the queue for the current thread pool. + +`rejected`, `r`:: +(Default) Number of tasks rejected by the thread pool executor. + +`completed`, `c`:: +Number of tasks completed by the thread pool executor. + +`core`, `cr`:: +Configured core number of active threads allowed in the current thread pool. + +`ephemeral_id`,`eid`:: +Ephemeral node ID. + +`host`, `h`:: +Hostname for the current node. + +`ip`, `i`:: +IP address for the current node. + +`keep_alive`, `k`:: +Configured keep alive time for threads. + +`largest`, `l`:: +Highest number of active threads in the current thread pool. + +`max`, `mx`:: +Configured maximum number of active threads allowed in the current thread pool. + +`node_id`, `id`:: +ID of the node, such as `k0zy`. + +`pid`, `p`:: +Process ID of the running node. + +`pool_size`, `psz`:: +Number of threads in the current thread pool. + +`port`, `po`:: +Bound transport port for the current node. + +`queue_size`, `qs`:: +Maximum number of tasks permitted in the queue for the current thread pool. + +`size`, `sz`:: +Configured fixed number of active threads allowed in the current thread pool. + +`type`, `t`:: +Type of thread pool. Returned values are `fixed` or `scaling`. + +-- + +include::{docdir}/rest-api/common-parms.asciidoc[tag=help] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=local] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s] + +`size`:: +(Optional, <>) Multiplier used to display quantities. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v] + + +[[cat-thread-pool-api-example]] +==== {api-examples-title} + +[[cat-thread-pool-api-ex-default]] +===== Example with default columns [source,js] -------------------------------------------------- @@ -10,7 +121,7 @@ GET /_cat/thread_pool -------------------------------------------------- // CONSOLE -Which looks like: +The API returns the following response: [source,txt] -------------------------------------------------- @@ -33,66 +144,13 @@ node-0 write 0 0 0 // know how many there will be and we just want to assert that there are // numbers in the response, not *which* numbers are there. -The first column is the node name -[source,txt] --------------------------------------------------- -node_name -node-0 --------------------------------------------------- +[[cat-thread-pool-api-ex-headings]] +===== Example with explicit columns -The second column is the thread pool name -[source,txt] --------------------------------------------------- -name -analyze -ccr (default distro only) -fetch_shard_started -fetch_shard_store -flush -force_merge -generic -get -listener -management -ml_autodetect (default distro only) -ml_datafeed (default distro only) -ml_utility (default distro only) -refresh -rollup_indexing (default distro only) -search -security-token-key (default distro only) -snapshot -warmer -watcher (default distro only) -write --------------------------------------------------- - - -The next three columns show the active, queue, and rejected statistics for each thread pool - -[source,txt] --------------------------------------------------- -active queue rejected - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 1 0 0 - 0 0 0 - 0 0 0 - 0 0 0 - 0 0 0 --------------------------------------------------- - -The cat thread pool API accepts a `thread_pool_patterns` URL parameter for specifying a -comma-separated list of regular expressions to match thread pool names. +The following API request returns the `id`, `name`, `active`, `rejected`, and +`completed` columns. The request limits returned information to the `generic` +thread pool. [source,js] -------------------------------------------------- @@ -100,7 +158,7 @@ GET /_cat/thread_pool/generic?v&h=id,name,active,rejected,completed -------------------------------------------------- // CONSOLE -which looks like: +The API returns the following response: [source,txt] -------------------------------------------------- @@ -109,46 +167,3 @@ id name active rejected completed -------------------------------------------------- // TESTRESPONSE[s/0EWUhXeBQtaVGlexUeVwMg/[\\w-]+/ s/\d+/\\d+/ non_json] -Here the host columns and the active, rejected and completed suggest thread pool statistics are displayed. - -All <> and custom thread pools are available. -[float] -===== Thread Pool Fields - -For each thread pool, you can load details about it by using the field names -in the table below. - -[cols="<,<,<",options="header"] -|======================================================================= -|Field Name |Alias |Description -|`type` |`t` |The current (*) type of thread pool (`fixed` or `scaling`) -|`active` |`a` |The number of active threads in the current thread pool -|`pool_size` |`psz` |The number of threads in the current thread pool -|`queue` |`q` |The number of tasks in the queue for the current thread pool -|`queue_size` |`qs` |The maximum number of tasks permitted in the queue for the current thread pool -|`rejected` |`r` |The number of tasks rejected by the thread pool executor -|`largest` |`l` |The highest number of active threads in the current thread pool -|`completed` |`c` |The number of tasks completed by the thread pool executor -|`core` |`cr` |The configured core number of active threads allowed in the current thread pool -|`max` |`mx` |The configured maximum number of active threads allowed in the current thread pool -|`size` |`sz` |The configured fixed number of active threads allowed in the current thread pool -|`keep_alive` |`k` |The configured keep alive time for threads -|======================================================================= - -[float] -==== Other Fields - -In addition to details about each thread pool, it is also convenient to get an -understanding of where those thread pools reside. As such, you can request -other details like the `ip` of the responding node(s). - -[cols="<,<,<",options="header"] -|======================================================================= -|Field Name |Alias |Description -|`node_id` |`id` |The unique node ID -|`ephemeral_id`|`eid` |The ephemeral node ID -|`pid` |`p` |The process ID of the running node -|`host` |`h` |The hostname for the current node -|`ip` |`i` |The IP address for the current node -|`port` |`po` |The bound transport port for the current node -|=======================================================================