2013-11-14 20:14:39 -05:00
[[cat-nodes]]
2019-08-13 08:35:08 -04:00
=== cat nodes API
++++
<titleabbrev>cat nodes</titleabbrev>
++++
2013-11-14 20:14:39 -05:00
2019-08-08 08:37:22 -04:00
Returns information about a cluster's nodes.
[[cat-nodes-api-request]]
==== {api-request-title}
`GET /_cat/nodes`
[[cat-nodes-api-query-params]]
==== {api-query-parms-title}
2019-10-10 09:48:40 -04:00
include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
2019-08-08 08:37:22 -04:00
include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
`full_id`::
(Optional, boolean) If `true`, return the full node ID. If `false`, return the
shortened node ID. Defaults to `false`.
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:
`ip`, `i`::
(Default) IP address, such as `127.0.1.1`.
`heap.percent`, `hp`, `heapPercent`::
(Default) Maximum configured heap, such as `7`.
`ram.percent`, `rp`, `ramPercent`::
(Default) Used total memory percentage, such as `47`.
`file_desc.percent`, `fdp`, `fileDescriptorPercent`::
(Default) Used file descriptors percentage, such as `1`.
`node.role`, `r`, `role`, `nodeRole`::
(Default) Roles of the node. Returned values include `m` (master-eligible node),
`d` (data node), `i` (ingest node), and `-` (coordinating node only).
+
For example, `mdi` indicates a master-eligible data and ingest node.
`master`, `m`::
(Default) Indicates whether the node is the elected master node. Returned values
include `*` (elected master) and `-` (not elected master).
`name`, `n`::
(Default) Node name, such as `I8hydUG`.
`id`, `nodeId`::
ID of the node, such as `k0zy`.
`pid`, `p`::
Process ID, such as `13061`.
`port`, `po`::
Bound transport port, such as `9300`.
`http_address`, `http`::
Bound http address, such as `127.0.0.1:9200`.
`version`, `v`::
Elasticsearch version, such as {version}.
`build`, `b`::
Elasticsearch build hash, such as `5c03844`.
`jdk`, `j`::
Java version, such as `1.8.0`.
`disk.total`, `dt`, `diskTotal`::
Total disk space, such as `458.3gb`.
`disk.used`, `du`, `diskUsed`::
Used disk space, such as `259.8gb`.
`disk.avail`, `d`, `disk`, `diskAvail`::
Available disk space, such as `198.4gb`.
`disk.used_percent`, `dup`, `diskUsedPercent`::
Used disk space percentage, such as `198.4gb`.
`heap.current`, `hc`, `heapCurrent`::
Used heap, such as `311.2mb`.
`ram.current`,`rc`, `ramCurrent`::
Used total memory, such as `513.4mb`.
`ram.max`, `rm`, `ramMax`::
Total memory, such as `2.9gb`.
`file_desc.current`, `fdc`, `fileDescriptorCurrent`::
Used file descriptors, such as `123`.
`file_desc.max`, `fdm`, `fileDescriptorMax`::
Maximum number of file descriptors, such as `1024`.
`cpu`::
Recent system CPU usage as percent, such as `12`.
`load_1m`, `l`::
Most recent load average, such as `0.22`.
`load_5m`, `l`::
Load average for the last five minutes, such as `0.78`.
`load_15m`, `l`::
Load average for the last fifteen minutes, such as `1.24`.
`uptime`, `u`::
Node uptime, such as `17.3m`.
`completion.size`, `cs`, `completionSize`::
Size of completion, such as `0b`.
`fielddata.memory_size`, `fm`, `fielddataMemory`::
Used fielddata cache memory, such as `0b`.
`fielddata.evictions`, `fe`, `fielddataEvictions`::
Fielddata cache evictions, such as `0`.
`query_cache.memory_size`, `qcm`, `queryCacheMemory`::
Used query cache memory, such as `0b`.
`query_cache.evictions`, `qce`, `queryCacheEvictions`::
Query cache evictions, such as `0`.
`request_cache.memory_size`, `rcm`, `requestCacheMemory`::
Used request cache memory, such as `0b`.
`request_cache.evictions`, `rce`, `requestCacheEvictions`::
Request cache evictions, such as `0`.
`request_cache.hit_count`, `rchc`, `requestCacheHitCount`::
Request cache hit count, such as `0`.
`request_cache.miss_count`, `rcmc`, `requestCacheMissCount`::
Request cache miss count, such as `0`.
`flush.total`, `ft`, `flushTotal`::
Number of flushes, such as `1`.
`flush.total_time`, `ftt`, `flushTotalTime`::
Time spent in flush, such as `1`.
`get.current`, `gc`, `getCurrent`::
Number of current get operations, such as `0`.
`get.time`, `gti`, `getTime`::
Time spent in get, such as `14ms`.
`get.total`, `gto`, `getTotal`::
Number of get operations, such as `2`.
`get.exists_time`, `geti`, `getExistsTime`::
Time spent in successful gets, such as `14ms`.
`get.exists_total`, `geto`, `getExistsTotal`::
Number of successful get operations, such as `2`.
`get.missing_time`, `gmti`, `getMissingTime`::
Time spent in failed gets, such as `0s`.
`get.missing_total`, `gmto`, `getMissingTotal`::
Number of failed get operations, such as `1`.
`indexing.delete_current`, `idc`, `indexingDeleteCurrent`::
Number of current deletion operations, such as `0`.
`indexing.delete_time`, `idti`, `indexingDeleteTime`::
Time spent in deletions, such as `2ms`.
`indexing.delete_total`, `idto`, `indexingDeleteTotal`::
Number of deletion operations, such as `2`.
`indexing.index_current`, `iic`, `indexingIndexCurrent`::
Number of current indexing operations, such as `0`.
`indexing.index_time`, `iiti`, `indexingIndexTime`::
Time spent in indexing, such as `134ms`.
`indexing.index_total`, `iito`, `indexingIndexTotal`::
Number of indexing operations, such as `1`.
`indexing.index_failed`, `iif`, `indexingIndexFailed`::
Number of failed indexing operations, such as `0`.
`merges.current`, `mc`, `mergesCurrent`::
Number of current merge operations, such as `0`.
`merges.current_docs`, `mcd`, `mergesCurrentDocs`::
Number of current merging documents, such as `0`.
`merges.current_size`, `mcs`, `mergesCurrentSize`::
Size of current merges, such as `0b`.
`merges.total`, `mt`, `mergesTotal`::
Number of completed merge operations, such as `0`.
`merges.total_docs`, `mtd`, `mergesTotalDocs`::
Number of merged documents, such as `0`.
`merges.total_size`, `mts`, `mergesTotalSize`::
Size of current merges, such as `0b`.
`merges.total_time`, `mtt`, `mergesTotalTime`::
Time spent merging documents, such as `0s`.
`refresh.total`, `rto`, `refreshTotal`::
Number of refreshes, such as `16`.
`refresh.time`, `rti`, `refreshTime`::
Time spent in refreshes, such as `91ms`.
`script.compilations`, `scrcc`, `scriptCompilations`::
Total script compilations, such as `17`.
`script.cache_evictions`, `scrce`, `scriptCacheEvictions`::
Total compiled scripts evicted from cache, such as `6`.
`search.fetch_current`, `sfc`, `searchFetchCurrent`::
Current fetch phase operations, such as `0`.
`search.fetch_time`, `sfti`, `searchFetchTime`::
Time spent in fetch phase, such as `37ms`.
`search.fetch_total`, `sfto`, `searchFetchTotal`::
Number of fetch operations, such as `7`.
`search.open_contexts`, `so`, `searchOpenContexts`::
Open search contexts, such as `0`.
`search.query_current`, `sqc`, `searchQueryCurrent`::
Current query phase operations, such as `0`.
`search.query_time`, `sqti`, `searchQueryTime`::
Time spent in query phase, such as `43ms`.
`search.query_total`, `sqto`, `searchQueryTotal`::
Number of query operations, such as `9`.
`search.scroll_current`, `scc`, `searchScrollCurrent`::
Open scroll contexts, such as `2`.
`search.scroll_time`, `scti`, `searchScrollTime`::
Time scroll contexts held open, such as `2m`.
`search.scroll_total`, `scto`, `searchScrollTotal`::
Completed scroll contexts, such as `1`.
`segments.count`, `sc`, `segmentsCount`::
Number of segments, such as `4`.
`segments.memory`, `sm`, `segmentsMemory`::
Memory used by segments, such as `1.4kb`.
`segments.index_writer_memory`, `siwm`, `segmentsIndexWriterMemory`::
Memory used by index writer, such as `18mb`.
`segments.version_map_memory`, `svmm`, `segmentsVersionMapMemory`::
Memory used by version map, such as `1.0kb`.
`segments.fixed_bitset_memory`, `sfbm`, `fixedBitsetMemory`::
Memory used by fixed bit sets for nested object field types and type filters for
types referred in <<parent-join,`join`>> fields, such as `1.0kb`.
`suggest.current`, `suc`, `suggestCurrent`::
Number of current suggest operations, such as `0`.
`suggest.time`, `suti`, `suggestTime`::
Time spent in suggest, such as `0`.
`suggest.total`, `suto`, `suggestTotal`::
Number of suggest operations, such as `0`.
--
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]
2019-10-10 09:48:40 -04:00
include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
2019-08-08 08:37:22 -04:00
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
[[cat-nodes-api-example]]
==== {api-examples-title}
[[cat-nodes-api-ex-default]]
===== Example with default columns
2013-11-14 20:14:39 -05:00
2019-09-09 13:38:14 -04:00
[source,console]
2013-11-14 20:14:39 -05:00
--------------------------------------------------
2016-10-13 16:42:21 -04:00
GET /_cat/nodes?v
2013-11-14 20:14:39 -05:00
--------------------------------------------------
2019-08-08 08:37:22 -04:00
The API returns the following response:
2013-11-14 20:14:39 -05:00
2016-10-25 10:56:30 -04:00
[source,txt]
2013-11-14 20:14:39 -05:00
--------------------------------------------------
2016-10-13 16:42:21 -04:00
ip heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
2019-06-13 14:43:14 -04:00
127.0.0.1 65 99 42 3.07 dim * mJw06l1
2013-11-14 20:14:39 -05:00
--------------------------------------------------
2016-10-13 16:42:21 -04:00
// TESTRESPONSE[s/3.07/(\\d+\\.\\d+( \\d+\\.\\d+ (\\d+\\.\\d+)?)?)?/]
// TESTRESPONSE[s/65 99 42/\\d+ \\d+ \\d+/]
2019-08-06 12:58:46 -04:00
// TESTRESPONSE[s/dim/.+/ s/[*]/[*]/ s/mJw06l1/.+/ non_json]
2013-11-14 20:14:39 -05:00
2019-08-08 08:37:22 -04:00
The `ip`, `heap.percent`, `ram.percent`, `cpu`, and `load_*` columns provide the
IP addresses and performance information of each node.
2014-03-27 01:19:54 -04:00
2019-08-08 08:37:22 -04:00
The `node.role`, `master`, and `name` columns provide information useful for
monitoring an entire cluster, particularly large ones.
2014-03-27 01:19:54 -04:00
2019-08-08 08:37:22 -04:00
[[cat-nodes-api-ex-headings]]
===== Example with explicit columns
The following API request returns the `id`, `ip`, `port`, `v` (version), and `m`
(master) columns.
2014-03-27 01:19:54 -04:00
2019-09-09 13:38:14 -04:00
[source,console]
2016-10-13 16:42:21 -04:00
--------------------------------------------------
GET /_cat/nodes?v&h=id,ip,port,v,m
--------------------------------------------------
2019-08-08 08:37:22 -04:00
The API returns the following response:
2016-10-13 16:42:21 -04:00
Enforce that responses in docs are valid json (#26249)
All of the snippets in our docs marked with `// TESTRESPONSE` are
checked against the response from Elasticsearch but, due to the
way they are implemented they are actually parsed as YAML instead
of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately
that means that invalid JSON has snuck into the exmples!
This adds a step during the build to parse them as JSON and fail
the build if they don't parse.
But no! It isn't quite that simple. The displayed text of some of
these responses looks like:
```
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
Note the `...` which isn't valid json but we like it anyway and want
it in the output. We use substitution rules to convert the `...`
into the response we expect. That yields a response that looks like:
```
{
"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
That is what the tests consume but it isn't valid JSON! Oh no! We don't
want to go update all the substitution rules because that'd be huge and,
ultimately, wouldn't buy much. So we quote the `$body.took` bits before
parsing the JSON.
Note the responses that we use for the `_cat` APIs are all converted into
regexes and there is no expectation that they are valid JSON.
Closes #26233
2017-08-17 09:02:10 -04:00
["source","txt",subs="attributes,callouts"]
2014-03-27 01:19:54 -04:00
--------------------------------------------------
2016-10-13 16:42:21 -04:00
id ip port v m
veJR 127.0.0.1 59938 {version} *
2014-03-27 01:19:54 -04:00
--------------------------------------------------
2019-08-08 08:37:22 -04:00
// TESTRESPONSE[s/veJR/.+/ s/59938/\\d+/ s/[*]/[*]/ non_json]
