Skip to content

Commit

Permalink
[DOCS] Reformats cluster node info API (elastic#45446)
Browse files Browse the repository at this point in the history
Co-Authored-By: James Rodewig <[email protected]>
  • Loading branch information
szabosteve and jrodewig committed Aug 13, 2019
1 parent 4ee7ac2 commit 356a632
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 98 deletions.
235 changes: 139 additions & 96 deletions docs/reference/cluster/nodes-info.asciidoc
Original file line number Diff line number Diff line change
@@ -1,125 +1,185 @@
[[cluster-nodes-info]]
=== Nodes Info

The cluster nodes info API allows to retrieve one or more (or all) of
the cluster nodes information.
Returns cluster nodes information.

[source,js]
--------------------------------------------------
GET /_nodes
GET /_nodes/nodeId1,nodeId2
--------------------------------------------------
// CONSOLE

The first command retrieves information of all the nodes in the cluster.
The second command selectively retrieves nodes information of only
`nodeId1` and `nodeId2`. All the nodes selective options are explained
[[cluster-nodes-info-api-request]]
==== {api-request-title}

`GET /_nodes` +

`GET /_nodes/{node_id}` +

`GET /_nodes/{metric}` +

`GET /_nodes/{node_id}/{metric}`


[[cluster-nodes-info-api-desc]]
==== {api-description-title}

The cluster nodes info API allows to retrieve one or more (or all) of
the cluster nodes information. All the nodes selective options are explained
<<cluster-nodes,here>>.

By default, it just returns all attributes and core settings for a node:
By default, it returns all attributes and core settings for a node.

[float]
[[core-info]]

`build_hash`::
Short hash of the last git commit in this release.
[[cluster-nodes-info-api-path-params]]
==== {api-path-parms-title}

`host`::
The node's host name.
`{metric}`::
(Optional, string) Limits the information returned to the specific metrics.
A comma-separated list of the following options:
+
--

`ip`::
The node's IP address.

`name`::
The node's name.
`http`::
HTTP connection information.

`total_indexing_buffer`::
Total heap allowed to be used to hold recently indexed
documents before they must be written to disk. This size is
a shared pool across all shards on this node, and is
controlled by <<indexing-buffer,Indexing Buffer settings>>.
`ingest`::
Statistics about ingest preprocessing.

`total_indexing_buffer_in_bytes`::
Same as `total_indexing_buffer`, but expressed in bytes.
`jvm`::
JVM stats, memory pool information, garbage collection, buffer pools, number
of loaded/unloaded classes.

`transport_address`::
Host and port where transport HTTP connections are accepted.
`os`::
Operating system stats, load average, mem, swap.

`plugins`::
Details about the installed plugins and modules per node. The following
information are available for each plugin and module:
+
---
* `name`: plugin name
* `version`: version of Elasticsearch the plugin was built for
* `description`: short description of the plugin's purpose
* `classname`: fully-qualified class name of the plugin's entry point
* `has_native_controller`: whether or not the plugin has a native controller
process
---

`process`::
Process statistics, memory consumption, cpu usage, open file descriptors.

`version`::
Elasticsearch version running on this node.
`settings`::

It also allows to get only information on `settings`, `os`, `process`, `jvm`,
`thread_pool`, `transport`, `http`, `plugins`, `ingest` and `indices`:
`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.
--

[source,js]
--------------------------------------------------
# return just process
GET /_nodes/process

# same as above
GET /_nodes/_all/process
include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]

# return just jvm and process of only nodeId1 and nodeId2
GET /_nodes/nodeId1,nodeId2/jvm,process

# same as above
GET /_nodes/nodeId1,nodeId2/info/jvm,process
[[cluster-nodes-info-api-response-body]]
==== {api-response-body-title}

# return all the information of only nodeId1 and nodeId2
GET /_nodes/nodeId1,nodeId2/_all
--------------------------------------------------
// CONSOLE
`build_hash`::
Short hash of the last git commit in this release.

`host`::
The node's host name.

`ip`::
The node's IP address.

The `_all` flag can be set to return all the information - or you can simply omit it.
`name`::
The node's name.

`total_indexing_buffer`::
Total heap allowed to be used to hold recently indexed
documents before they must be written to disk. This size is
a shared pool across all shards on this node, and is
controlled by <<indexing-buffer,Indexing Buffer settings>>.

`total_indexing_buffer_in_bytes`::
Same as `total_indexing_buffer`, but expressed in bytes.

[float]
[[os-info]]
==== Operating System information
`transport_address`::
Host and port where transport HTTP connections are accepted.

`version`::
{es} version running on this node.

The `os` flag can be set to retrieve information that concern
the operating system:
system:

`os.refresh_interval_in_millis`::
Refresh interval for the OS statistics
Refresh interval for the OS statistics

`os.name`::
Name of the operating system (ex: Linux, Windows, Mac OS X)
Name of the operating system (ex: Linux, Windows, Mac OS X)

`os.arch`::
Name of the JVM architecture (ex: amd64, x86)
Name of the JVM architecture (ex: amd64, x86)

`os.version`::
Version of the operating system
Version of the operating system

`os.available_processors`::
Number of processors available to the Java virtual machine
Number of processors available to the Java virtual machine

`os.allocated_processors`::
The number of processors actually used to calculate thread pool size. This number can be set
with the `processors` setting of a node and defaults to the number of processors reported by the OS.
In both cases this number will never be larger than 32.
The number of processors actually used to calculate thread pool size. This
number can be set with the `processors` setting of a node and defaults to
the number of processors reported by the OS. In both cases this number will
never be larger than 32.

[float]
[[process-info]]
==== Process information

The `process` flag can be set to retrieve information that concern
the current running process:
The `process` flag can be set to retrieve information that concern the current
running process:

`process.refresh_interval_in_millis`::
Refresh interval for the process statistics
Refresh interval for the process statistics

`process.id`::
Process identifier (PID)
Process identifier (PID)

`process.mlockall`::
Indicates if the process address space has been successfully locked in memory
Indicates if the process address space has been successfully locked in memory


[[cluster-nodes-info-api-query-params]]
==== {api-query-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]

include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[cluster-nodes-info-api-example]]
==== {api-examples-title}

[source,js]
--------------------------------------------------
# return just process
GET /_nodes/process
[float]
[[plugins-info]]
==== Plugins information
# same as above
GET /_nodes/_all/process
# return just jvm and process of only nodeId1 and nodeId2
GET /_nodes/nodeId1,nodeId2/jvm,process
# same as above
GET /_nodes/nodeId1,nodeId2/info/jvm,process
# return all the information of only nodeId1 and nodeId2
GET /_nodes/nodeId1,nodeId2/_all
--------------------------------------------------
// CONSOLE

`plugins` - if set, the result will contain details about the installed plugins and modules per node:
The `_all` flag can be set to return all the information - or you can omit it.

If `plugins` is specified, the result will contain details about the installed
plugins and modules:

[source,js]
--------------------------------------------------
Expand All @@ -128,7 +188,7 @@ GET /_nodes/plugins
// CONSOLE
// TEST[setup:node]

The result will look similar to:
The API returns the following response:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -186,20 +246,7 @@ The result will look similar to:
// TESTRESPONSE[s/"plugins": \[[^\]]*\]/"plugins": $body.$_path/]
// TESTRESPONSE[s/"modules": \[[^\]]*\]/"modules": $body.$_path/]

The following information are available for each plugin and module:

* `name`: plugin name
* `version`: version of Elasticsearch the plugin was built for
* `description`: short description of the plugin's purpose
* `classname`: fully-qualified class name of the plugin's entry point
* `has_native_controller`: whether or not the plugin has a native controller process


[float]
[[ingest-info]]
==== Ingest information

`ingest` - if set, the result will contain details about the available
If `ingest` is specified, the response contains details about the available
processors per node:

[source,js]
Expand All @@ -209,7 +256,7 @@ GET /_nodes/ingest
// CONSOLE
// TEST[setup:node]

The result will look similar to:
The API returns the following response:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -289,7 +336,3 @@ The result will look similar to:
// TESTRESPONSE[s/"roles": \[[^\]]*\]/"roles": $body.$_path/]
// TESTRESPONSE[s/"attributes": \{[^\}]*\}/"attributes": $body.$_path/]
// TESTRESPONSE[s/"processors": \[[^\]]*\]/"processors": $body.$_path/]

The following information are available for each ingest processor:

* `type`: the processor type
4 changes: 2 additions & 2 deletions docs/reference/ingest/ingest-node.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -828,8 +828,8 @@ See <<ingest-conditionals>> to learn more about the `if` field and conditional e

See <<handling-failure-in-pipelines>> to learn more about the `on_failure` field and error handling in pipelines.

The <<ingest-info,node info API>> can be used to figure out what processors are available in a cluster.
The <<ingest-info,node info API>> will provide a per node list of what processors are available.
The <<cluster-nodes-info,node info API>> can be used to figure out what processors are available in a cluster.
The <<cluster-nodes-info,node info API>> will provide a per node list of what processors are available.

Custom processors must be installed on all nodes. The put pipeline API will fail if a processor specified in a pipeline
doesn't exist on all nodes. If you rely on custom processor plugins make sure to mark these plugins as mandatory by adding
Expand Down

0 comments on commit 356a632

Please sign in to comment.