From 4ee7ac25aef6e110c38a130388b40c51061f6016 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 13 Aug 2019 12:46:47 +0200 Subject: [PATCH] [DOCS] Reformats cluster node stats API (#45441) Co-Authored-By: James Rodewig --- docs/reference/cluster/nodes-stats.asciidoc | 741 +++++++++++--------- docs/reference/ingest/ingest-node.asciidoc | 2 +- 2 files changed, 392 insertions(+), 351 deletions(-) diff --git a/docs/reference/cluster/nodes-stats.asciidoc b/docs/reference/cluster/nodes-stats.asciidoc index 452d821bedd..3ce78cabcd3 100644 --- a/docs/reference/cluster/nodes-stats.asciidoc +++ b/docs/reference/cluster/nodes-stats.asciidoc @@ -1,72 +1,406 @@ [[cluster-nodes-stats]] === Nodes Stats -[float] -==== Nodes statistics +Returns cluster nodes statistics. -The cluster nodes stats API allows to retrieve one or more (or all) of -the cluster nodes statistics. -[source,js] --------------------------------------------------- -GET /_nodes/stats -GET /_nodes/nodeId1,nodeId2/stats --------------------------------------------------- -// CONSOLE +[[cluster-nodes-stats-api-request]] +==== {api-request-title} -The first command retrieves stats of all the nodes in the cluster. The -second command selectively retrieves nodes stats of only `nodeId1` and -`nodeId2`. All the nodes selective options are explained -<>. +`GET /_nodes/stats` + -By default, all stats are returned. You can limit this by combining any -of `indices`, `os`, `process`, `jvm`, `transport`, `http`, -`fs`, `breaker` and `thread_pool`. For example: +`GET /_nodes/{node_id}/stats` + -[horizontal] -`indices`:: - Indices stats about size, document count, indexing and - deletion times, search times, field cache size, merges and flushes +`GET/_nodes/stats/{metric}` + -`fs`:: - File system information, data path, free disk space, read/write - stats (see <>) +`GET/_nodes/{node_id}/stats/{metric}` + -`http`:: - HTTP connection information +`GET /_nodes/stats/{metric}/{index_metric}` + -`jvm`:: - JVM stats, memory pool information, garbage collection, buffer - pools, number of loaded/unloaded classes +`GET /_nodes/{node_id}/stats/{metric}/{index_metric}` -`os`:: - Operating system stats, load average, mem, swap - (see <>) -`process`:: - Process statistics, memory consumption, cpu usage, open - file descriptors (see <>) +[[cluster-nodes-stats-api-desc]] +==== {api-description-title} -`thread_pool`:: - Statistics about each thread pool, including current - size, queue and rejected tasks +You can use the cluster nodes stats API to retrieve statistics for nodes in a cluster. -`transport`:: - Transport statistics about sent and received bytes in - cluster communication -`breaker`:: - Statistics about the field data circuit breaker +All the nodes selective options are explained <>. -`discovery`:: - Statistics about the discovery +By default, all stats are returned. You can limit the returned information by +using metrics. -`ingest`:: - Statistics about ingest preprocessing +[[cluster-nodes-stats-api-path-params]] +==== {api-path-parms-title} -`adaptive_selection`:: - Statistics about <>. See - <>. + +`{metric}`:: + (Optional, string) Limits the information returned to the specific metrics. + A comma-separated list of the following options: ++ +-- + `adaptive_selection`:: + Statistics about <>. + + `breaker`:: + Statistics about the field data circuit breaker. + + `discovery`:: + Statistics about the discovery. + + `fs`:: + File system information, data path, free disk space, read/write + stats. + + `http`:: + HTTP connection information. + + `indices`:: + Indices stats about size, document count, indexing and deletion times, + search times, field cache size, merges and flushes. + + `ingest`:: + Statistics about ingest preprocessing. + + `jvm`:: + JVM stats, memory pool information, garbage collection, buffer + pools, number of loaded/unloaded classes. + + `os`:: + Operating system stats, load average, mem, swap. + + `process`:: + Process statistics, memory consumption, cpu usage, open + file descriptors. + + `thread_pool`:: + Statistics about each thread pool, including current size, queue and + rejected tasks. + + `transport`:: + Transport statistics about sent and received bytes in cluster + communication. +-- + +`{index_metric}`:: + (Optional, string) Limit the information returned for `indices` metric to + the specific index metrics. It can be used only if `indices` (or `all`) + metric is specified. Supported metrics are: ++ +-- + * `completion` + * `docs` + * `fielddata` + * `flush` + * `get` + * `indexing` + * `merge` + * `query_cache` + * `recovery` + * `refresh` + * `request_cache` + * `search` + * `segments` + * `store` + * `translog` + * `warmer` +-- + +include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id] + + +[[cluster-nodes-stats-api-query-params]] +==== {api-query-parms-title} + +`completion_fields`:: + (Optional, string) A comma-separated list of fields for `fielddata` and + `suggest` index metric (supports wildcards). + +`fielddata_fields`:: + (Optional, string) A comma-separated list of fields for `fielddata` index + metric (supports wildcards). + +`fields`:: + (Optional, string) A comma-separated list of fields for `fielddata` and + `completion` index metric (supports wildcards). + +`groups`:: + (Optional, string) A comma-separated list of search groups for `search` + index metric. + +`level`:: + (Optional, string) Returns indices stats aggregated at index, node or shard + level. Supported options: `indices`, `node`, `shards`. + +`types`:: + (Optional, string) A comma-separated list of document types for the + `indexing` index metric. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +`include_segment_file_sizes`:: + (Optional, boolean) If `true`, the call reports the aggregated disk usage of + each one of the Lucene index files (only applies if segment stats are + requested). Defaults to `false`. + + +[[cluster-nodes-stats-api-response-body]] +==== {api-response-body-title} + +The `fs` flag can be set to retrieve information that concern the file system: + +`fs.timestamp`:: + Last time the file stores statistics have been refreshed. + +`fs.total.total_in_bytes`:: + Total size (in bytes) of all file stores. + +`fs.total.free_in_bytes`:: + Total number of unallocated bytes in all file stores. + +`fs.total.available_in_bytes`:: + Total number of bytes available to this Java virtual machine on all file + stores. Depending on OS or process level restrictions, this might appear + less than `fs.total.free_in_bytes`. This is the actual amount of free disk + space the {es} node can utilise. + +`fs.data`:: + List of all file stores. + +`fs.data.path`:: + Path to the file store. + +`fs.data.mount`:: + Mount point of the file store (ex: /dev/sda2). + +`fs.data.type`:: + Type of the file store (ex: ext4). + +`fs.data.total_in_bytes`:: + Total size (in bytes) of the file store. + +`fs.data.free_in_bytes`:: + Total number of unallocated bytes in the file store. + +`fs.data.available_in_bytes`:: + Total number of bytes available to this Java virtual machine on this file + store. + +`fs.io_stats.devices` (Linux only):: + Array of disk metrics for each device that is backing an {es} data path. + These disk metrics are probed periodically and averages between the last + probe and the current probe are computed. + +`fs.io_stats.devices.device_name` (Linux only):: + The Linux device name. + +`fs.io_stats.devices.operations` (Linux only):: + The total number of read and write operations for the device completed since + starting {es}. + +`fs.io_stats.devices.read_operations` (Linux only):: + The total number of read operations for the device completed since starting + {es}. + +`fs.io_stats.devices.write_operations` (Linux only):: + The total number of write operations for the device completed since starting + {es}. + +`fs.io_stats.devices.read_kilobytes` (Linux only):: + The total number of kilobytes read for the device since starting {es}. + +`fs.io_stats.devices.write_kilobytes` (Linux only):: + The total number of kilobytes written for the device since starting {es}. + +`fs.io_stats.operations` (Linux only):: + The total number of read and write operations across all devices used by + {es} completed since starting {es}. + +`fs.io_stats.read_operations` (Linux only):: + The total number of read operations for across all devices used by {es} + completed since starting {es}. + +`fs.io_stats.write_operations` (Linux only):: + The total number of write operations across all devices used by {es} + completed since starting {es}. + +`fs.io_stats.read_kilobytes` (Linux only):: + The total number of kilobytes read across all devices used by {es} since + starting {es}. + +`fs.io_stats.write_kilobytes` (Linux only):: + The total number of kilobytes written across all devices used by {es} since + starting {es}. + +The `os` flag can be set to retrieve statistics that concern +the operating system: + +`os.timestamp`:: + Last time the operating system statistics have been refreshed. + +`os.cpu.percent`:: + Recent CPU usage for the whole system, or -1 if not supported. + +`os.cpu.load_average.1m`:: + One-minute load average on the system (field is not present if one-minute + load average is not available). + +`os.cpu.load_average.5m`:: + Five-minute load average on the system (field is not present if five-minute + load average is not available). + +`os.cpu.load_average.15m`:: + Fifteen-minute load average on the system (field is not present if + fifteen-minute load average is not available). + +`os.mem.total_in_bytes`:: + Total amount of physical memory in bytes. + +`os.mem.free_in_bytes`:: + Amount of free physical memory in bytes. + +`os.mem.free_percent`:: + Percentage of free memory. + +`os.mem.used_in_bytes`:: + Amount of used physical memory in bytes. + +`os.mem.used_percent`:: + Percentage of used memory. + +`os.swap.total_in_bytes`:: + Total amount of swap space in bytes. + +`os.swap.free_in_bytes`:: + Amount of free swap space in bytes. + +`os.swap.used_in_bytes`:: + Amount of used swap space in bytes. + +`os.cgroup.cpuacct.control_group` (Linux only):: + The `cpuacct` control group to which the {es} process belongs. + +`os.cgroup.cpuacct.usage_nanos` (Linux only):: + The total CPU time (in nanoseconds) consumed by all tasks in the same cgroup + as the {es} process. + +`os.cgroup.cpu.control_group` (Linux only):: + The `cpu` control group to which the {es} process belongs. + +`os.cgroup.cpu.cfs_period_micros` (Linux only):: + The period of time (in microseconds) for how regularly all tasks in the same + cgroup as the {es} process should have their access to CPU resources + reallocated. + +`os.cgroup.cpu.cfs_quota_micros` (Linux only):: + The total amount of time (in microseconds) for which all tasks in + the same cgroup as the {es} process can run during one period + `os.cgroup.cpu.cfs_period_micros`. + +`os.cgroup.cpu.stat.number_of_elapsed_periods` (Linux only):: + The number of reporting periods (as specified by + `os.cgroup.cpu.cfs_period_micros`) that have elapsed. + +`os.cgroup.cpu.stat.number_of_times_throttled` (Linux only):: + The number of times all tasks in the same cgroup as the {es} process have + been throttled. + +`os.cgroup.cpu.stat.time_throttled_nanos` (Linux only):: + The total amount of time (in nanoseconds) for which all tasks in the same + cgroup as the {es} process have been throttled. + +`os.cgroup.memory.control_group` (Linux only):: + The `memory` control group to which the {es} process belongs. + +`os.cgroup.memory.limit_in_bytes` (Linux only):: + The maximum amount of user memory (including file cache) allowed for all + tasks in the same cgroup as the {es} process. This value can be too big to + store in a `long`, so is returned as a string so that the value returned can + exactly match what the underlying operating system interface returns. Any + value that is too large to parse into a `long` almost certainly means no + limit has been set for the cgroup. + +`os.cgroup.memory.usage_in_bytes` (Linux only):: + The total current memory usage by processes in the cgroup (in bytes) by all + tasks in the same cgroup as the {es} process. This value is stored as a + string for consistency with `os.cgroup.memory.limit_in_bytes`. + +NOTE: For the cgroup stats to be visible, cgroups must be compiled into the +kernel, the `cpu` and `cpuacct` cgroup subsystems must be configured and stats +must be readable from `/sys/fs/cgroup/cpu` and `/sys/fs/cgroup/cpuacct`. + +The `process` flag can be set to retrieve statistics that concern +the current running process: + +`process.timestamp`:: + Last time the process statistics have been refreshed. + +`process.open_file_descriptors`:: + Number of opened file descriptors associated with the current process, or -1 + if not supported. + +`process.max_file_descriptors`:: + Maximum number of file descriptors allowed on the system, or -1 if not + supported. + +`process.cpu.percent`:: + CPU usage in percent, or -1 if not known at the time the stats are computed + +`process.cpu.total_in_millis`:: + CPU time (in milliseconds) used by the process on which the Java virtual + machine is running, or -1 if not supported. + +`process.mem.total_virtual_in_bytes`:: + Size in bytes of virtual memory that is guaranteed to be available to the + running process. + +The `ingest` flag can be set to retrieve statistics that concern ingest: + +`ingest.total.count`:: + The total number of document ingested during the lifetime of this node + +`ingest.total.time_in_millis`:: + The total time spent on ingest preprocessing documents during the lifetime + of this node. + +`ingest.total.current`:: + The total number of documents currently being ingested. + +`ingest.total.failed`:: + The total number ingest preprocessing operations failed during the lifetime + of this node. + +On top of these overall ingest statistics, these statistics are also provided on +a per pipeline basis. + +The `adaptive_selection` flag can be set to retrieve statistics that concern +<>. These statistics are +keyed by node. For each node: + +`adaptive_selection.outgoing_searches`:: + The number of outstanding search requests from the node these stats are for + to the keyed node. + +`avg_queue_size`:: + The exponentially weighted moving average queue size of search requests on + the keyed node. + +`avg_service_time_ns`:: + The exponentially weighted moving average service time of search requests on + the keyed node. + +`avg_response_time_ns`:: + The exponentially weighted moving average response time of search requests + on the keyed node. + +`rank`:: + The rank of this node; used for shard selection when routing search + requests. + + +[[cluster-nodes-stats-api-example]] +==== {api-examples-title} [source,js] -------------------------------------------------- @@ -81,243 +415,21 @@ GET /_nodes/10.0.0.1/stats/process -------------------------------------------------- // CONSOLE -All stats can be explicitly requested via `/_nodes/stats/_all` or `/_nodes/stats?metric=_all`. +All stats can be explicitly requested via `/_nodes/stats/_all` or +`/_nodes/stats?metric=_all`. -[float] -[[fs-info]] -===== FS information - -The `fs` flag can be set to retrieve -information that concern the file system: - -`fs.timestamp`:: - Last time the file stores statistics have been refreshed - -`fs.total.total_in_bytes`:: - Total size (in bytes) of all file stores - -`fs.total.free_in_bytes`:: - Total number of unallocated bytes in all file stores - -`fs.total.available_in_bytes`:: - Total number of bytes available to this Java virtual machine on all file stores. - Depending on OS or process level restrictions, this might appear less than `fs.total.free_in_bytes`. - This is the actual amount of free disk space the Elasticsearch node can utilise. - -`fs.data`:: - List of all file stores - -`fs.data.path`:: - Path to the file store - -`fs.data.mount`:: - Mount point of the file store (ex: /dev/sda2) - -`fs.data.type`:: - Type of the file store (ex: ext4) - -`fs.data.total_in_bytes`:: - Total size (in bytes) of the file store - -`fs.data.free_in_bytes`:: - Total number of unallocated bytes in the file store - -`fs.data.available_in_bytes`:: - Total number of bytes available to this Java virtual machine on this file store - -`fs.io_stats.devices` (Linux only):: - Array of disk metrics for each device that is backing an - Elasticsearch data path. These disk metrics are probed periodically - and averages between the last probe and the current probe are - computed. - -`fs.io_stats.devices.device_name` (Linux only):: - The Linux device name. - -`fs.io_stats.devices.operations` (Linux only):: - The total number of read and write operations for the device - completed since starting Elasticsearch. - -`fs.io_stats.devices.read_operations` (Linux only):: - The total number of read operations for the device completed since - starting Elasticsearch. - -`fs.io_stats.devices.write_operations` (Linux only):: - The total number of write operations for the device completed since - starting Elasticsearch. - -`fs.io_stats.devices.read_kilobytes` (Linux only):: - The total number of kilobytes read for the device since starting - Elasticsearch. - -`fs.io_stats.devices.write_kilobytes` (Linux only):: - The total number of kilobytes written for the device since - starting Elasticsearch. - -`fs.io_stats.operations` (Linux only):: - The total number of read and write operations across all devices - used by Elasticsearch completed since starting Elasticsearch. - -`fs.io_stats.read_operations` (Linux only):: - The total number of read operations for across all devices used by - Elasticsearch completed since starting Elasticsearch. - -`fs.io_stats.write_operations` (Linux only):: - The total number of write operations across all devices used by - Elasticsearch completed since starting Elasticsearch. - -`fs.io_stats.read_kilobytes` (Linux only):: - The total number of kilobytes read across all devices used by - Elasticsearch since starting Elasticsearch. - -`fs.io_stats.write_kilobytes` (Linux only):: - The total number of kilobytes written across all devices used by - Elasticsearch since starting Elasticsearch. - -[float] -[[os-stats]] -===== Operating System statistics - -The `os` flag can be set to retrieve statistics that concern -the operating system: - -`os.timestamp`:: - Last time the operating system statistics have been refreshed - -`os.cpu.percent`:: - Recent CPU usage for the whole system, or -1 if not supported - -`os.cpu.load_average.1m`:: - One-minute load average on the system (field is not present if - one-minute load average is not available) -`os.cpu.load_average.5m`:: - Five-minute load average on the system (field is not present if - five-minute load average is not available) -`os.cpu.load_average.15m`:: - Fifteen-minute load average on the system (field is not present if - fifteen-minute load average is not available) - -`os.mem.total_in_bytes`:: - Total amount of physical memory in bytes - -`os.mem.free_in_bytes`:: - Amount of free physical memory in bytes - -`os.mem.free_percent`:: - Percentage of free memory - -`os.mem.used_in_bytes`:: - Amount of used physical memory in bytes - -`os.mem.used_percent`:: - Percentage of used memory - -`os.swap.total_in_bytes`:: - Total amount of swap space in bytes - -`os.swap.free_in_bytes`:: - Amount of free swap space in bytes - -`os.swap.used_in_bytes`:: - Amount of used swap space in bytes - -`os.cgroup.cpuacct.control_group` (Linux only):: - The `cpuacct` control group to which the Elasticsearch process - belongs - -`os.cgroup.cpuacct.usage_nanos` (Linux only):: - The total CPU time (in nanoseconds) consumed by all tasks in the - same cgroup as the Elasticsearch process - -`os.cgroup.cpu.control_group` (Linux only):: - The `cpu` control group to which the Elasticsearch process belongs - -`os.cgroup.cpu.cfs_period_micros` (Linux only):: - The period of time (in microseconds) for how regularly all tasks in - the same cgroup as the Elasticsearch process should have their - access to CPU resources reallocated. - -`os.cgroup.cpu.cfs_quota_micros` (Linux only):: - The total amount of time (in microseconds) for which all tasks in - the same cgroup as the Elasticsearch process can run during one - period `os.cgroup.cpu.cfs_period_micros` - -`os.cgroup.cpu.stat.number_of_elapsed_periods` (Linux only):: - The number of reporting periods (as specified by - `os.cgroup.cpu.cfs_period_micros`) that have elapsed - -`os.cgroup.cpu.stat.number_of_times_throttled` (Linux only):: - The number of times all tasks in the same cgroup as the - Elasticsearch process have been throttled. - -`os.cgroup.cpu.stat.time_throttled_nanos` (Linux only):: - The total amount of time (in nanoseconds) for which all tasks in - the same cgroup as the Elasticsearch process have been throttled. - -`os.cgroup.memory.control_group` (Linux only):: - The `memory` control group to which the Elasticsearch process - belongs - -`os.cgroup.memory.limit_in_bytes` (Linux only):: - The maximum amount of user memory (including file cache) allowed - for all tasks in the same cgroup as the Elasticsearch process. - This value can be too big to store in a `long`, so is returned as - a string so that the value returned can exactly match what the - underlying operating system interface returns. Any value that is - too large to parse into a `long` almost certainly means no limit - has been set for the cgroup. - -`os.cgroup.memory.usage_in_bytes` (Linux only):: - The total current memory usage by processes in the cgroup (in bytes) - by all tasks in the same cgroup as the Elasticsearch process. - This value is stored as a string for consistency with - `os.cgroup.memory.limit_in_bytes`. - -NOTE: For the cgroup stats to be visible, cgroups must be compiled into -the kernel, the `cpu` and `cpuacct` cgroup subsystems must be -configured and stats must be readable from `/sys/fs/cgroup/cpu` -and `/sys/fs/cgroup/cpuacct`. - -[float] -[[process-stats]] -===== Process statistics - -The `process` flag can be set to retrieve statistics that concern -the current running process: - -`process.timestamp`:: - Last time the process statistics have been refreshed - -`process.open_file_descriptors`:: - Number of opened file descriptors associated with the current process, or -1 if not supported - -`process.max_file_descriptors`:: - Maximum number of file descriptors allowed on the system, or -1 if not supported - -`process.cpu.percent`:: - CPU usage in percent, or -1 if not known at the time the stats are computed - -`process.cpu.total_in_millis`:: - CPU time (in milliseconds) used by the process on which the Java virtual machine is running, or -1 if not supported - -`process.mem.total_virtual_in_bytes`:: - Size in bytes of virtual memory that is guaranteed to be available to the running process - -[float] -[[node-indices-stats]] -==== Indices statistics - -You can get information about indices stats on `node`, `indices`, or `shards` level. +You can get information about indices stats on `node`, `indices`, or `shards` +level. [source,js] -------------------------------------------------- -# Fielddata summarised by node +# Fielddata summarized by node GET /_nodes/stats/indices/fielddata?fields=field1,field2 -# Fielddata summarised by node and index +# Fielddata summarized by node and index GET /_nodes/stats/indices/fielddata?level=indices&fields=field1,field2 -# Fielddata summarised by node, index, and shard +# Fielddata summarized by node, index, and shard GET /_nodes/stats/indices/fielddata?level=shards&fields=field1,field2 # You can use wildcards for field names @@ -325,29 +437,6 @@ GET /_nodes/stats/indices/fielddata?fields=field* -------------------------------------------------- // CONSOLE -Supported metrics are: - -* `completion` -* `docs` -* `fielddata` -* `flush` -* `get` -* `indexing` -* `merge` -* `query_cache` -* `recovery` -* `refresh` -* `request_cache` -* `search` -* `segments` -* `store` -* `translog` -* `warmer` - -[float] -[[search-groups]] -==== Search groups - You can get statistics about search groups for searches executed on this node. @@ -360,51 +449,3 @@ GET /_nodes/stats?groups=_all GET /_nodes/stats/indices?groups=foo,bar -------------------------------------------------- // CONSOLE - -[float] -[[ingest-stats]] -==== Ingest statistics - -The `ingest` flag can be set to retrieve statistics that concern ingest: - -`ingest.total.count`:: - The total number of document ingested during the lifetime of this node - -`ingest.total.time_in_millis`:: - The total time spent on ingest preprocessing documents during the lifetime of this node - -`ingest.total.current`:: - The total number of documents currently being ingested. - -`ingest.total.failed`:: - The total number ingest preprocessing operations failed during the lifetime of this node - -On top of these overall ingest statistics, these statistics are also provided on a per pipeline basis. - -[float] -[[adaptive-selection-stats]] -==== Adaptive selection statistics - -The `adaptive_selection` flag can be set to retrieve statistics that concern -<>. These statistics are -keyed by node. For each node: - -`adaptive_selection.outgoing_searches`:: - The number of outstanding search requests from the node these stats are for to - the keyed node. - -`avg_queue_size`:: - The exponentially weighted moving average queue size of search requests on the - keyed node. - -`avg_service_time_ns`:: - The exponentially weighted moving average service time of search requests on - the keyed node. - -`avg_response_time_ns`:: - The exponentially weighted moving average response time of search requests on - the keyed node. - -`rank`:: - The rank of this node; used for shard selection when routing search requests. - diff --git a/docs/reference/ingest/ingest-node.asciidoc b/docs/reference/ingest/ingest-node.asciidoc index 4a9ed038964..e3971f33b8d 100644 --- a/docs/reference/ingest/ingest-node.asciidoc +++ b/docs/reference/ingest/ingest-node.asciidoc @@ -842,7 +842,7 @@ plugin.mandatory: ingest-attachment A node will not start if this plugin is not available. -The <> can be used to fetch ingest usage statistics, globally and on a per +The <> can be used to fetch ingest usage statistics, globally and on a per pipeline basis. Useful to find out which pipelines are used the most or spent the most time on preprocessing. [float]