Cluster APIs
Node specification
Some cluster-level APIs may operate on a subset of the nodes which can be specified with node filters. For example, the Task Management, Nodes Stats, and Nodes Info APIs can all report results from a filtered set of nodes rather than from all nodes.
Node filters are written as a comma-separated list of individual filters, each of which adds or removes nodes from the chosen subset. Each filter can be one of the following:
-
_all
, to add all nodes to the subset. -
_local
, to add the local node to the subset. -
_master
, to add the currently-elected master node to the subset. -
a node id or name, to add this node to the subset.
-
an IP address or hostname, to add all matching nodes to the subset.
-
a pattern, using
*
wildcards, which adds all nodes to the subset whose name, address or hostname matches the pattern. -
master:true
,data:true
,ingest:true
orcoordinating_only:true
, which respectively add to the subset all master-eligible nodes, all data nodes, all ingest nodes, and all coordinating-only nodes. -
master:false
,data:false
,ingest:false
orcoordinating_only:false
, which respectively remove from the subset all master-eligible nodes, all data nodes, all ingest nodes, and all coordinating-only nodes. -
a pair of patterns, using
*
wildcards, of the formattrname:attrvalue
, which adds to the subset all nodes with a custom node attribute whose name and value match the respective patterns. Custom node attributes are configured by setting properties in the configuration file of the formnode.attr.attrname: attrvalue
.
|
Note
|
node filters run in the order in which they are given, which is important
if using filters that remove nodes from the set. For example
_all,master:false means all the nodes except the master-eligible ones, but
master:false,_all means the same as _all because the _all filter runs
after the master:false filter.
|
|
Note
|
if no filters are given, the default is to select all nodes. However, if
any filters are given then they run starting with an empty chosen subset. This
means that filters such as master:false which remove nodes from the chosen
subset are only useful if they come after some other filters. When used on its
own, master:false selects no nodes.
|
Here are some examples of the use of node filters with the Nodes Info APIs.
# If no filters are given, the default is to select all nodes
GET /_nodes
# Explicitly select all nodes
GET /_nodes/_all
# Select just the local node
GET /_nodes/_local
# Select the elected master node
GET /_nodes/_master
# Select nodes by name, which can include wildcards
GET /_nodes/node_name_goes_here
GET /_nodes/node_name_goes_*
# Select nodes by address, which can include wildcards
GET /_nodes/<IP_ADDRESS>,<IP_ADDRESS>
GET /_nodes/10.0.0.*
# Select nodes by role
GET /_nodes/_all,master:false
GET /_nodes/data:true,ingest:true
GET /_nodes/coordinating_only:true
# Select nodes by custom attribute (e.g. with something like `node.attr.rack: 2` in the configuration file)
GET /_nodes/rack:2
GET /_nodes/ra*:2
GET /_nodes/ra*:2*
Cluster allocation explain API
Provides explanations for shard allocations in the cluster.
Request
GET /_cluster/allocation/explain
Description
The purpose of the cluster allocation explain API is to provide explanations for shard allocations in the cluster. For unassigned shards, the explain API provides an explanation for why the shard is unassigned. For assigned shards, the explain API provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
Query parameters
include_disk_info
-
(Optional, Boolean) If
true
, returns information about disk usage and shard sizes. Defaults tofalse
. include_yes_decisions
-
(Optional, Boolean) If
true
, returns 'YES' decisions in explanation. Defaults tofalse
.
Request body
current_node
-
(Optional, string) Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.
index
-
(Optional, string) Specifies the name of the index that you would like an explanation for.
primary
-
(Optional, Boolean) If
true
, returns explanation for the primary shard for the given shard ID. shard
-
(Optional, integer) Specifies the ID of the shard that you would like an explanation for.
You can also have OpenSearch explain the allocation of the first unassigned shard that it finds by sending an empty body for the request.
Examples
GET /_cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": true
}
Example of the current_node parameter
GET /_cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "nodeA" (1)
}
-
The node where shard 0 currently has a replica on
Examples of unassigned primary shard explanations
PUT /my-index-000001?master_timeout=1s&timeout=1s
{"settings": {"index.routing.allocation.include._name": "non_existent_node"} }
GET /_cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": true
}
The API returns the following response for an unassigned primary shard:
{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned", (1)
"unassigned_info" : {
"reason" : "INDEX_CREATED", (2)
"at" : "2017-01-04T18:08:16.600Z",
"last_allocation_status" : "no"
},
"can_allocate" : "no", (3)
"allocate_explanation" : "cannot allocate because allocation is not permitted to any of the nodes",
"node_allocation_decisions" : [
{
"node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
"node_name" : "node-0",
"transport_address" : "<IP_ADDRESS>:9401",
"node_attributes" : {},
"node_decision" : "no", (4)
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter", (5)
"decision" : "NO",
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]" (6)
}
]
}
]
}
-
The current state of the shard.
-
The reason for the shard originally becoming unassigned.
-
Whether to allocate the shard.
-
Whether to allocate the shard to the particular node.
-
The decider which led to the
no
decision for the node. -
An explanation as to why the decider returned a
no
decision, with a helpful hint pointing to the setting that led to the decision.
The API response output for an unassigned primary shard that had previously been allocated to a node in the cluster:
{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "NODE_LEFT",
"at" : "2017-01-04T18:03:28.464Z",
"details" : "node_left[OIWe8UhhThCK0V5XfmdrmQ]",
"last_allocation_status" : "no_valid_shard_copy"
},
"can_allocate" : "no_valid_shard_copy",
"allocate_explanation" : "cannot allocate because a previous copy of the primary shard existed but can no longer be found on the nodes in the cluster"
}
Example of an unassigned replica shard explanation
The API response output for a replica that is unassigned due to delayed allocation:
{
"index" : "my-index-000001",
"shard" : 0,
"primary" : false,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "NODE_LEFT",
"at" : "2017-01-04T18:53:59.498Z",
"details" : "node_left[G92ZwuuaRY-9n8_tc-IzEg]",
"last_allocation_status" : "no_attempt"
},
"can_allocate" : "allocation_delayed",
"allocate_explanation" : "cannot allocate because the cluster is still waiting 59.8s for the departed node holding a replica to rejoin, despite being allowed to allocate the shard to at least one other node",
"configured_delay" : "1m", (1)
"configured_delay_in_millis" : 60000,
"remaining_delay" : "59.8s", (2)
"remaining_delay_in_millis" : 59824,
"node_allocation_decisions" : [
{
"node_id" : "pmnHu_ooQWCPEFobZGbpWw",
"node_name" : "node_t2",
"transport_address" : "<IP_ADDRESS>:9402",
"node_decision" : "yes"
},
{
"node_id" : "3sULLVJrRneSg0EfBB-2Ew",
"node_name" : "node_t0",
"transport_address" : "<IP_ADDRESS>:9400",
"node_decision" : "no",
"store" : { (3)
"matching_size" : "4.2kb",
"matching_size_in_bytes" : 4325
},
"deciders" : [
{
"decider" : "same_shard",
"decision" : "NO",
"explanation" : "a copy of this shard is already allocated to this node [[my-index-000001][0], node[3sULLVJrRneSg0EfBB-2Ew], [P], s[STARTED], a[id=eV9P8BN1QPqRc3B4PLx6cg]]"
}
]
}
]
}
-
The configured delay before allocating a replica shard that does not exist due to the node holding it leaving the cluster.
-
The remaining delay before allocating the replica shard.
-
Information about the shard data found on a node.
Examples of allocated shard explanations
The API response output for an assigned shard that is not allowed to remain on its current node and is required to move:
{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "started",
"current_node" : {
"id" : "8lWJeJ7tSoui0bxrwuNhTA",
"name" : "node_t1",
"transport_address" : "<IP_ADDRESS>:9401"
},
"can_remain_on_current_node" : "no", (1)
"can_remain_decisions" : [ (2)
{
"decider" : "filter",
"decision" : "NO",
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]"
}
],
"can_move_to_other_node" : "no", (3)
"move_explanation" : "cannot move shard to another node, even though it is not allowed to remain on its current node",
"node_allocation_decisions" : [
{
"node_id" : "_P8olZS8Twax9u6ioN-GGA",
"node_name" : "node_t0",
"transport_address" : "<IP_ADDRESS>:9400",
"node_decision" : "no",
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter",
"decision" : "NO",
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]"
}
]
}
]
}
-
Whether the shard is allowed to remain on its current node.
-
The deciders that factored into the decision of why the shard is not allowed to remain on its current node.
-
Whether the shard is allowed to be allocated to another node.
The API response output for an assigned shard that remains on its current node because moving the shard to another node does not form a better cluster balance:
{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "started",
"current_node" : {
"id" : "wLzJm4N4RymDkBYxwWoJsg",
"name" : "node_t0",
"transport_address" : "<IP_ADDRESS>:9400",
"weight_ranking" : 1
},
"can_remain_on_current_node" : "yes",
"can_rebalance_cluster" : "yes", (1)
"can_rebalance_to_other_node" : "no", (2)
"rebalance_explanation" : "cannot rebalance as no target node exists that can both allocate this shard and improve the cluster balance",
"node_allocation_decisions" : [
{
"node_id" : "oE3EGFc8QN-Tdi5FFEprIA",
"node_name" : "node_t1",
"transport_address" : "<IP_ADDRESS>:9401",
"node_decision" : "worse_balance", (3)
"weight_ranking" : 1
}
]
}
-
Whether rebalancing is allowed on the cluster.
-
Whether the shard can be rebalanced to another node.
-
The reason the shard cannot be rebalanced to the node, in this case indicating that it offers no better balance than the current node.
Cluster get settings API
Returns cluster-wide settings.
GET /_cluster/settings
Request
GET /_cluster/settings
Description
By default, this API call only returns settings that have been explicitly
defined, but can also include the default settings by calling the
include_defaults
parameter.
Query parameters
flat_settings
-
(Optional, Boolean) If
true
, returns settings in flat format. Defaults tofalse
. include_defaults
-
(Optional, Boolean) If
true
, returns all default cluster settings. Defaults tofalse
. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Cluster health API
Returns the health status of a cluster.
Request
GET /_cluster/health/<target>
Description
The cluster health API returns a simple status on the health of the cluster. You can also use the API to get the health status of only specified indices.
The cluster health status is: green
, yellow
or red
. On the shard level, a
red
status indicates that the specific shard is not allocated in the cluster,
yellow
means that the primary shard is allocated but replicas are not, and
green
means that all shards are allocated. The index level status is
controlled by the worst shard status. The cluster status is controlled by the
worst index status.
One of the main benefits of the API is the ability to wait until the cluster
reaches a certain high water-mark health level. For example, the following will
wait for 50 seconds for the cluster to reach the yellow
level (if it reaches
the green
or yellow
status before 50 seconds elapse, it will return at that
point):
GET /_cluster/health?wait_for_status=yellow&timeout=50s
Path parameters
<target>
-
(Optional, string) Comma-separated list of indices and index aliases used to limit the request. Wildcard expressions (
*
) are supported.To target all indices in a cluster, omit this parameter or use
_all
or*
.
Query parameters
level
-
(Optional, string) Can be one of
cluster
,indices
orshards
. Controls the details level of the health information returned. Defaults tocluster
. local
-
(Optional, Boolean) If
true
, the request retrieves information from the local node only. Defaults tofalse
, which means information is retrieved from the master node. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. wait_for_active_shards
-
(Optional, string) A number controlling to how many active shards to wait for,
all
to wait for all shards in the cluster to be active, or0
to not wait. Defaults to0
. wait_for_events
-
(Optional, string) Can be one of
immediate
,urgent
,high
,normal
,low
,languid
. Wait until all currently queued events with the given priority are processed. wait_for_no_initializing_shards
-
(Optional, Boolean) A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
wait_for_no_relocating_shards
-
(Optional, Boolean) A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
wait_for_nodes
-
(Optional, string) The request waits until the specified number
N
of nodes is available. It also accepts>=N
,⇐N
,>N
and<N
. Alternatively, it is possible to usege(N)
,le(N)
,gt(N)
andlt(N)
notation. wait_for_status
-
(Optional, string) One of
green
,yellow
orred
. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e.green
>yellow
>red
. By default, will not wait for any status.
Response body
cluster_name
-
(string) The name of the cluster.
status
-
(string) Health status of the cluster, based on the state of its primary and replica shards. Statuses are:
green
-
All shards are assigned.
yellow
-
All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.
red
-
One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
timed_out
-
(Boolean) If
false
the response returned within the period of time that is specified by thetimeout
parameter (30s
by default). number_of_nodes
-
(integer) The number of nodes within the cluster.
number_of_data_nodes
-
(integer) The number of nodes that are dedicated data nodes.
active_primary_shards
-
(integer) The number of active primary shards.
active_shards
-
(integer) The total number of active primary and replica shards.
relocating_shards
-
(integer) The number of shards that are under relocation.
initializing_shards
-
(integer) The number of shards that are under initialization.
unassigned_shards
-
(integer) The number of shards that are not allocated.
delayed_unassigned_shards
-
(integer) The number of shards whose allocation has been delayed by the timeout settings.
number_of_pending_tasks
-
(integer) The number of cluster-level changes that have not yet been executed.
number_of_in_flight_fetch
-
(integer) The number of unfinished fetches.
task_max_waiting_in_queue_millis
-
(integer) The time expressed in milliseconds since the earliest initiated task is waiting for being performed.
active_shards_percent_as_number
-
(float) The ratio of active shards in the cluster expressed as a percentage.
Examples
GET _cluster/health
The API returns the following response in case of a quiet single node cluster with a single index with one shard and one replica:
{
"cluster_name" : "testcluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 1,
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
"active_shards_percent_as_number": 50.0
}
The following is an example of getting the cluster health at the
shards
level:
GET /_cluster/health/my-index-000001?level=shards
Cluster reroute API
Changes the allocation of shards in a cluster.
Request
POST /_cluster/reroute
Description
The reroute command allows for manual changes to the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be cancelled, and an unassigned shard can be explicitly allocated to a specific node.
It is important to note that after processing any reroute commands OpenSearch will
perform rebalancing as normal (respecting the values of settings such as
cluster.routing.rebalance.enable
) in order to remain in a balanced state. For
example, if the requested allocation includes moving a shard from node1
to
node2
then this may cause a shard to be moved from node2
back to node1
to
even things out.
The cluster can be set to disable allocations using the
cluster.routing.allocation.enable
setting. If allocations are disabled then
the only allocations that will be performed are explicit ones given using the
reroute
command, and consequent allocations due to rebalancing.
It is possible to run reroute
commands in "dry run" mode by using the
?dry_run
URI query parameter, or by passing "dry_run": true
in the request
body. This will calculate the result of applying the commands to the current
cluster state, and return the resulting cluster state after the commands (and
re-balancing) has been applied, but will not actually perform the requested
changes.
If the ?explain
URI query parameter is included then a detailed explanation
of why the commands could or could not be executed is included in the response.
The cluster will attempt to allocate a shard a maximum of
index.allocation.max_retries
times in a row (defaults to 5
), before giving
up and leaving the shard unallocated. This scenario can be caused by
structural problems such as having an analyzer which refers to a stopwords
file which doesn’t exist on all nodes.
Once the problem has been corrected, allocation can be manually retried by
calling the reroute
API with the ?retry_failed
URI
query parameter, which will attempt a single retry round for these shards.
Query parameters
dry_run
-
(Optional, Boolean) If
true
, then the request simulates the operation only and returns the resulting state. explain
-
(Optional, Boolean) If
true
, then the response contains an explanation of why the commands can or cannot be executed. metric
-
(Optional, string) Limits the information returned to the specified metrics. Defaults to all but metadata The following options are available:
Options for
metric
_all
-
Shows all metrics.
blocks
-
Shows the
blocks
part of the response. master_node
-
Shows the elected
master_node
part of the response. metadata
-
Shows the
metadata
part of the response. If you supply a comma separated list of indices, the returned output will only contain metadata for these indices. nodes
-
Shows the
nodes
part of the response. routing_table
-
Shows the
routing_table
part of the response. version
-
Shows the cluster state version.
retry_failed
-
(Optional, Boolean) If
true
, then retries allocation of shards that are blocked due to too many subsequent allocation failures. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Request body
commands
-
(Required, array of objects) Defines the commands to perform. Supported commands are:
Properties of
commands
move
-
Move a started shard from one node to another node. Accepts
index
andshard
for index name and shard number,from_node
for the node to move the shard from, andto_node
for the node to move the shard to. cancel
-
Cancel allocation of a shard (or recovery). Accepts
index
andshard
for index name and shard number, andnode
for the node to cancel the shard allocation on. This can be used to force resynchronization of existing replicas from the primary shard by cancelling them and allowing them to be reinitialized through the standard recovery process. By default only replica shard allocations can be cancelled. If it is necessary to cancel the allocation of a primary shard then theallow_primary
flag must also be included in the request. allocate_replica
-
Allocate an unassigned replica shard to a node. Accepts
index
andshard
for index name and shard number, andnode
to allocate the shard to. Takes allocation deciders into account.
Two more commands are available that allow the allocation of a primary shard to a node. These commands should however be used with extreme care, as primary shard allocation is usually fully automatically handled by OpenSearch. Reasons why a primary shard cannot be automatically allocated include the following:
-
A new index was created but there is no node which satisfies the allocation deciders.
-
An up-to-date shard copy of the data cannot be found on the current data nodes in the cluster. To prevent data loss, the system does not automatically promote a stale shard copy to primary.
The following two commands are dangerous and may result in data loss. They are meant to be used in cases where the original data can not be recovered and the cluster administrator accepts the loss. If you have suffered a temporary issue that can be fixed, please see the
retry_failed
flag described above. To emphasise: if these commands are performed and then a node joins the cluster that holds a copy of the affected shard then the copy on the newly-joined node will be deleted or overwritten.allocate_stale_primary
-
Allocate a primary shard to a node that holds a stale copy. Accepts the
index
andshard
for index name and shard number, andnode
to allocate the shard to. Using this command may lead to data loss for the provided shard id. If a node which has the good copy of the data rejoins the cluster later on, that data will be deleted or overwritten with the data of the stale copy that was forcefully allocated with this command. To ensure that these implications are well-understood, this command requires the flagaccept_data_loss
to be explicitly set totrue
. allocate_empty_primary
-
Allocate an empty primary shard to a node. Accepts the
index
andshard
for index name and shard number, andnode
to allocate the shard to. Using this command leads to a complete loss of all data that was indexed into this shard, if it was previously started. If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flagaccept_data_loss
to be explicitly set totrue
.
Examples
This is a short example of a simple reroute API call:
POST /_cluster/reroute
{
"commands": [
{
"move": {
"index": "test", "shard": 0,
"from_node": "node1", "to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test", "shard": 1,
"node": "node3"
}
}
]
}
Cluster state API
Returns metadata about the state of the cluster.
Request
GET /_cluster/state/<metrics>/<target>
Description
The cluster state API allows access to metadata representing the state of the whole cluster. This includes information such as
-
the set of nodes in the cluster
-
all cluster-level settings
-
information about the indices in the cluster, including their mappings and settings
-
the locations of all the shards in the cluster.
|
Note
|
The response is an internal representation of the cluster state and its format may change from version to version. If possible, you should obtain any information from the cluster state using the other, more stable, cluster APIs. |
The response provides the cluster state itself, which can be filtered to only retrieve the parts of interest as described below.
The cluster’s cluster_uuid
is also returned as part of the top-level response,
in addition to the metadata
section.
|
Note
|
While the cluster is still forming, it is possible for the cluster_uuid
to be na as well as the cluster state’s version to be -1 .
|
By default, the cluster state request is routed to the master node, to ensure
that the latest cluster state is returned. For debugging purposes, you can
retrieve the cluster state local to a particular node by adding local=true
to
the query string.
Path parameters
The cluster state contains information about all the indices in the cluster, including their mappings, as well as templates and other metadata. This means it can sometimes be quite large. To avoid the need to process all this information you can request only the part of the cluster state that you need:
<metrics>
-
(Optional, string) A comma-separated list of the following options:
_all
-
Shows all metrics.
blocks
-
Shows the
blocks
part of the response. master_node
-
Shows the elected
master_node
part of the response. metadata
-
Shows the
metadata
part of the response. If you supply a comma separated list of indices, the returned output will only contain metadata for these indices. nodes
-
Shows the
nodes
part of the response. routing_nodes
-
Shows the
routing_nodes
part of the response. routing_table
-
Shows the
routing_table
part of the response. If you supply a comma separated list of indices, the returned output will only contain the routing table for these indices. version
-
Shows the cluster state version.
<target>
-
(Optional, string) Comma-separated list of indices and index aliases used to limit the request. Wildcard expressions (
*
) are supported.To target all indices in a cluster, omit this parameter or use
_all
or*
.
Query parameters
allow_no_indices
-
(Optional, Boolean) If
true
, the wildcard indices expression that resolves into no concrete indices will be ignored. (This includes_all
string or when no indices have been specified).Defaults to
true
. expand_wildcards
-
(Optional, string) Whether to expand wildcard expression to concrete indices that are open, closed or both. Available options:
open
,closed
,none
,all
. flat_settings
-
(Optional, Boolean) If
true
, returns settings in flat format. Defaults tofalse
. ignore_unavailable
-
(Optional, Boolean) If
true
, unavailable indices (missing or closed) will be ignored. local
-
(Optional, Boolean) If
true
, the request retrieves information from the local node only. Defaults tofalse
, which means information is retrieved from the master node. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. wait_for_metadata_version
-
(Optional, integer) Waits for the metadata version to be equal or greater than the specified metadata version.
wait_for_timeout
-
(Optional, time units) Specifies the maximum time to wait for wait_for_metadata_version before timing out.
Examples
The following example returns only metadata
and routing_table
data for the
foo
and bar
indices:
GET /_cluster/state/metadata,routing_table/foo,bar
The next example returns all available metadata for foo
and bar
:
GET /_cluster/state/_all/foo,bar
This example returns only the blocks
metadata:
GET /_cluster/state/blocks
Cluster stats API
Returns cluster statistics.
Request
GET /_cluster/stats
GET /_cluster/stats/nodes/<node_filter>
Description
The Cluster Stats API allows to retrieve statistics from a cluster wide perspective. The API returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
Path parameters
<node_filter>
-
(Optional, string) Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.
Query parameters
timeout
-
(Optional, time units) Period to wait for each node to respond. If a node does not respond before its timeout expires, the response does not include its stats. However, timed out nodes are included in the response’s
_nodes.failed
property. Defaults to no timeout.
Response body
_nodes
-
(object) Contains statistics about the number of nodes selected by the request’s node filters.
Properties of
_nodes
total
-
(integer) Total number of nodes selected by the request.
successful
-
(integer) Number of nodes that responded successfully to the request.
failed
-
(integer) Number of nodes that rejected the request or failed to respond. If this value is not
0
, a reason for the rejection or failure is included in the response.
cluster_name
-
(string) Name of the cluster, based on the Cluster name setting setting.
cluster_uuid
-
(string) Unique identifier for the cluster.
timestamp
-
(integer) Unix timestamp, in milliseconds, of the last time the cluster statistics were refreshed.
status
-
(string) Health status of the cluster, based on the state of its primary and replica shards. Statuses are:
green
-
All shards are assigned.
yellow
-
All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.
red
-
One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
See Cluster health API.
indices
-
(object) Contains statistics about indices with shards assigned to selected nodes.
Properties of
indices
count
-
(integer) Total number of indices with shards assigned to selected nodes.
shards
-
(object) Contains statistics about shards assigned to selected nodes.
Properties of
shards
total
-
(integer) Total number of shards assigned to selected nodes.
primaries
-
(integer) Number of primary shards assigned to selected nodes.
replication
-
(float) Ratio of replica shards to primary shards across all selected nodes.
index
-
(object) Contains statistics about shards assigned to selected nodes.
Properties of
index
shards
-
(object) Contains statistics about the number of shards assigned to selected nodes.
Properties of
shards
min
-
(integer) Minimum number of shards in an index, counting only shards assigned to selected nodes.
max
-
(integer) Maximum number of shards in an index, counting only shards assigned to selected nodes.
avg
-
(float) Mean number of shards in an index, counting only shards assigned to selected nodes.
primaries
-
(object) Contains statistics about the number of primary shards assigned to selected nodes.
Properties of
primaries
min
-
(integer) Minimum number of primary shards in an index, counting only shards assigned to selected nodes.
max
-
(integer) Maximum number of primary shards in an index, counting only shards assigned to selected nodes.
avg
-
(float) Mean number of primary shards in an index, counting only shards assigned to selected nodes.
replication
-
(object) Contains statistics about the number of replication shards assigned to selected nodes.
Properties of
replication
min
-
(float) Minimum replication factor in an index, counting only shards assigned to selected nodes.
max
-
(float) Maximum replication factor in an index, counting only shards assigned to selected nodes.
avg
-
(float) Mean replication factor in an index, counting only shards assigned to selected nodes.
docs
-
(object) Contains counts for documents in selected nodes.
Properties of
docs
count
-
(integer) Total number of non-deleted documents across all primary shards assigned to selected nodes.
This number is based on documents in Lucene segments and may include documents from nested fields.
deleted
-
(integer) Total number of deleted documents across all primary shards assigned to selected nodes.
This number is based on documents in Lucene segments. OpenSearch reclaims the disk space of deleted Lucene documents when a segment is merged.
store
-
(object) Contains statistics about the size of shards assigned to selected nodes.
Properties of
store
size
-
(byte units) Total size of all shards assigned to selected nodes.
size_in_bytes
-
(integer) Total size, in bytes, of all shards assigned to selected nodes.
reserved
-
(byte value) A prediction of how much larger the shard stores will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities.
reserved_in_bytes
-
(integer) A prediction, in bytes, of how much larger the shard stores will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities.
fielddata
-
(object) Contains statistics about the field data cache of selected nodes.
Properties of
fielddata
memory_size
-
(byte units) Total amount of memory used for the field data cache across all shards assigned to selected nodes.
memory_size_in_bytes
-
(integer) Total amount, in bytes, of memory used for the field data cache across all shards assigned to selected nodes.
evictions
-
(integer) Total number of evictions from the field data cache across all shards assigned to selected nodes.
query_cache
-
(object) Contains statistics about the query cache of selected nodes.
Properties of
query_cache
memory_size
-
(byte units) Total amount of memory used for the query cache across all shards assigned to selected nodes.
memory_size_in_bytes
-
(integer) Total amount, in bytes, of memory used for the query cache across all shards assigned to selected nodes.
total_count
-
(integer) Total count of hits and misses in the query cache across all shards assigned to selected nodes.
hit_count
-
(integer) Total count of query cache hits across all shards assigned to selected nodes.
miss_count
-
(integer) Total count of query cache misses across all shards assigned to selected nodes.
cache_size
-
(integer) Total number of entries currently in the query cache across all shards assigned to selected nodes.
cache_count
-
(integer) Total number of entries added to the query cache across all shards assigned to selected nodes. This number includes current and evicted entries.
evictions
-
(integer) Total number of query cache evictions across all shards assigned to selected nodes.
completion
-
(object) Contains statistics about memory used for completion in selected nodes.
Properties of
completion
size
-
(byte units) Total amount of memory used for completion across all shards assigned to selected nodes.
size_in_bytes
-
(integer) Total amount, in bytes, of memory used for completion across all shards assigned to selected nodes.
segments
-
(object) Contains statistics about segments in selected nodes.
Properties of
segments
count
-
(integer) Total number of segments across all shards assigned to selected nodes.
memory
-
(byte units) Total amount of memory used for segments across all shards assigned to selected nodes.
memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for segments across all shards assigned to selected nodes.
terms_memory
-
(byte units) Total amount of memory used for terms across all shards assigned to selected nodes.
terms_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for terms across all shards assigned to selected nodes.
stored_fields_memory
-
(byte units) Total amount of memory used for stored fields across all shards assigned to selected nodes.
stored_fields_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for stored fields across all shards assigned to selected nodes.
term_vectors_memory
-
(byte units) Total amount of memory used for term vectors across all shards assigned to selected nodes.
term_vectors_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for term vectors across all shards assigned to selected nodes.
norms_memory
-
(byte units) Total amount of memory used for normalization factors across all shards assigned to selected nodes.
norms_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for normalization factors across all shards assigned to selected nodes.
points_memory
-
(byte units) Total amount of memory used for points across all shards assigned to selected nodes.
points_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for points across all shards assigned to selected nodes.
doc_values_memory
-
(byte units) Total amount of memory used for doc values across all shards assigned to selected nodes.
doc_values_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used for doc values across all shards assigned to selected nodes.
index_writer_memory
-
(byte units) Total amount of memory used by all index writers across all shards assigned to selected nodes.
index_writer_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used by all index writers across all shards assigned to selected nodes.
version_map_memory
-
(byte units) Total amount of memory used by all version maps across all shards assigned to selected nodes.
version_map_memory_in_bytes
-
(integer) Total amount, in bytes, of memory used by all version maps across all shards assigned to selected nodes.
fixed_bit_set
-
(byte units) Total amount of memory used by fixed bit sets across all shards assigned to selected nodes.
Fixed bit sets are used for nested object field types and type filters for join fields.
fixed_bit_set_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used by fixed bit sets across all shards assigned to selected nodes.
max_unsafe_auto_id_timestamp
-
(integer) Unix timestamp, in milliseconds, of the most recently retried indexing request.
file_sizes
-
(object) This object is not populated by the cluster stats API.
To get information on segment files, use the node stats API.
mappings
-
(object) Contains statistics about field mappings in selected nodes.
Properties of
mappings
field_types
-
(array of objects) Contains statistics about field data types used in selected nodes.
Properties of
field_types
objectsname
-
(string) Field data type used in selected nodes.
count
-
(integer) Number of fields mapped to the field data type in selected nodes.
index_count
-
(integer) Number of indices containing a mapping of the field data type in selected nodes.
analysis
-
(object) Contains statistics about analyzers and analyzer components used in selected nodes.
Properties of
analysis
char_filter_types
-
(array of objects) Contains statistics about character filter types used in selected nodes.
Properties of
char_filter_types
objectsname
-
(string) Character filter type used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the character filter type in selected nodes.
index_count
-
(integer) Number of indices the character filter type in selected nodes.
tokenizer_types
-
(array of objects) Contains statistics about tokenizer types used in selected nodes.
Properties of
tokenizer_types
objectsname
-
(string) Tokenizer type used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the tokenizer type in selected nodes.
index_count
-
(integer) Number of indices using the tokenizer type in selected nodes.
filter_types
-
(array of objects) Contains statistics about token filter types used in selected nodes.
Properties of
filter_types
objectsname
-
(string) Token filter type used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the token filter type in selected nodes.
index_count
-
(integer) Number of indices using the token filter type in selected nodes.
analyzer_types
-
(array of objects) Contains statistics about analyzer types used in selected nodes.
Properties of
analyzer_types
objectsname
-
(string) Analyzer type used in selected nodes.
count
-
(integer) Occurrences of the analyzer type in selected nodes.
index_count
-
(integer) Number of indices using the analyzer type in selected nodes.
built_in_char_filters
-
(array of objects) Contains statistics about built-in character filters used in selected nodes.
Properties of
built_in_char_filters
objectsname
-
(string) Built-in character filter used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the built-in character filter in selected nodes.
index_count
-
(integer) Number of indices using the built-in character filter in selected nodes.
built_in_tokenizers
-
(array of objects) Contains statistics about built-in tokenizers used in selected nodes.
Properties of
built_in_tokenizers
objectsname
-
(string) Built-in tokenizer used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the built-in tokenizer in selected nodes.
index_count
-
(integer) Number of indices using the built-in tokenizer in selected nodes.
built_in_filters
-
(array of objects) Contains statistics about built-in token filters used in selected nodes.
Properties of
built_in_filters
objectsname
-
(string) Built-in token filter used in selected nodes.
count
-
(integer) Number of analyzers or normalizers using the built-in token filter in selected nodes.
index_count
-
(integer) Number of indices using the built-in token filter in selected nodes.
built_in_analyzers
-
(array of objects) Contains statistics about built-in analyzers used in selected nodes.
Properties of
built_in_analyzers
objectsname
-
(string) Built-in analyzer used in selected nodes.
count
-
(integer) Occurrences of the built-in analyzer in selected nodes.
index_count
-
(integer) Number of indices using the built-in analyzer in selected nodes.
nodes
-
(object) Contains statistics about nodes selected by the request’s node filters.
Properties of
nodes
count
-
(object) Contains counts for nodes selected by the request’s node filters.
Properties of
count
total
-
(integer) Total number of selected nodes.
coordinating_only
-
(integer) Number of selected nodes without a role. These nodes are considered coordinating only nodes.
<role>
-
(integer) Number of selected nodes with the role. For a list of roles, see Node.
versions
-
(array of strings) Array of OpenSearch versions used on selected nodes.
os
-
(object) Contains statistics about the operating systems used by selected nodes.
Properties of
os
available_processors
-
(integer) Number of processors available to JVM across all selected nodes.
allocated_processors
-
(integer) Number of processors used to calculate thread pool size across all selected nodes.
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 than32
. names
-
(array of objects) Contains statistics about operating systems used by selected nodes.
Properties of
names
name
-
(string) Name of an operating system used by one or more selected nodes.
count
-
(string) Number of selected nodes using the operating system.
pretty_names
-
(array of objects) Contains statistics about operating systems used by selected nodes.
Properties of
pretty_names
pretty_name
-
(string) Human-readable name of an operating system used by one or more selected nodes.
count
-
(string) Number of selected nodes using the operating system.
mem
-
(object) Contains statistics about memory used by selected nodes.
Properties of
mem
total
-
(byte units) Total amount of physical memory across all selected nodes.
total_in_bytes
-
(integer) Total amount, in bytes, of physical memory across all selected nodes.
free
-
(byte units) Amount of free physical memory across all selected nodes.
free_in_bytes
-
(integer) Amount, in bytes, of free physical memory across all selected nodes.
used
-
(byte units) Amount of physical memory in use across all selected nodes.
used_in_bytes
-
(integer) Amount, in bytes, of physical memory in use across all selected nodes.
free_percent
-
(integer) Percentage of free physical memory across all selected nodes.
used_percent
-
(integer) Percentage of physical memory in use across all selected nodes.
process
-
(object) Contains statistics about processes used by selected nodes.
Properties of
process
cpu
-
(object) Contains statistics about CPU used by selected nodes.
Properties of
cpu
percent
-
(integer) Percentage of CPU used across all selected nodes. Returns
-1
if not supported.
open_file_descriptors
-
(object) Contains statistics about open file descriptors in selected nodes.
Properties of
open_file_descriptors
min
-
(integer) Minimum number of concurrently open file descriptors across all selected nodes. Returns
-1
if not supported. max
-
(integer) Maximum number of concurrently open file descriptors allowed across all selected nodes. Returns
-1
if not supported. avg
-
(integer) Average number of concurrently open file descriptors. Returns
-1
if not supported.
jvm
-
(object) Contains statistics about the Java Virtual Machines (JVMs) used by selected nodes.
Properties of
jvm
max_uptime
-
(time unit) Uptime duration since JVM last started.
max_uptime_in_millis
-
(integer) Uptime duration, in milliseconds, since JVM last started.
versions
-
(array of objects) Contains statistics about the JVM versions used by selected nodes.
Properties of
versions
version
-
(string) Version of JVM used by one or more selected nodes.
vm_name
-
(string) Name of the JVM.
vm_version
-
(string) Full version number of JVM.
The full version number includes a plus sign (
+
) followed by the build number. vm_vendor
-
(string) Vendor of the JVM.
bundled_jdk
-
(Boolean) If
true
, the JVM includes a bundled Java Development Kit (JDK). using_bundled_jdk
-
(Boolean) If
true
, a bundled JDK is in use by JVM. count
-
(integer) Total number of selected nodes using JVM.
mem
-
(object) Contains statistics about memory used by selected nodes.
Properties of
mem
heap_used
-
(byte units) Memory currently in use by the heap across all selected nodes.
heap_used_in_bytes
-
(integer) Memory, in bytes, currently in use by the heap across all selected nodes.
heap_max
-
(byte units) Maximum amount of memory, in bytes, available for use by the heap across all selected nodes.
heap_max_in_bytes
-
(integer) Maximum amount of memory, in bytes, available for use by the heap across all selected nodes.
threads
-
(integer) Number of active threads in use by JVM across all selected nodes.
fs
-
(object) Contains statistics about file stores by selected nodes.
Properties of
fs
total
-
(byte units) Total size of all file stores across all selected nodes.
total_in_bytes
-
(integer) Total size, in bytes, of all file stores across all seleced nodes.
free
-
(byte units) Amount of unallocated disk space in file stores across all selected nodes.
free_in_bytes
-
(integer) Total number of unallocated bytes in file stores across all selected nodes.
available
-
(byte units) Total amount of disk space available to JVM in file stores across all selected nodes.
Depending on OS or process-level restrictions, this amount may be less than
nodes.fs.free
. This is the actual amount of free disk space the selected OpenSearch nodes can use. available_in_bytes
-
(integer) Total number of bytes available to JVM in file stores across all selected nodes.
Depending on OS or process-level restrictions, this number may be less than
nodes.fs.free_in_byes
. This is the actual amount of free disk space the selected OpenSearch nodes can use.
plugins
-
(array of objects) Contains statistics about installed plugins and modules by selected nodes.
If no plugins or modules are installed, this array is empty.
Properties of
plugins
<plugin>
-
(object) Contains statistics about an installed plugin or module.
Properties of
<plugin>
name
-
(string) Name of the OpenSearch plugin.
version
-
(string) OpenSearch version for which the plugin was built.
opensearch_version
-
(string) OpenSearch version for which the plugin was built.
java_version
-
(string) Java version for which the plugin was built.
description
-
(string) Short description of the plugin.
classname
-
(string) Class name used as the plugin’s entry point.
extended_plugins
-
(array of strings) An array of other plugins extended by this plugin through the Java Service Provider Interface (SPI).
If this plugin extends no other plugins, this array is empty.
has_native_controller
-
(Boolean) If
true
, the plugin has a native controller process.
network_types
-
(object) Contains statistics about the transport and HTTP networks used by selected nodes.
Properties of
network_types
transport_types
-
(object) Contains statistics about the transport network types used by selected nodes.
Properties of
transport_types
<transport_type>
-
(integer) Number of selected nodes using the transport type.
http_types
-
(object) Contains statistics about the HTTP network types used by selected nodes.
Properties of
http_types
<http_type>
-
(integer) Number of selected nodes using the HTTP type.
discovery_types
-
(object) Contains statistics about the discovery types used by selected nodes.
Properties of
discovery_types
<discovery_type>
-
(integer) Number of selected nodes using the discovery type to find other nodes.
packaging_types
-
(array of objects) Contains statistics about OpenSearch distributions installed on selected nodes.
Properties of
packaging_types
flavor
-
(string) Type of OpenSearch distribution, such as
default
orOSS
, used by one or more selected nodes. type
-
(string) File type, such as
tar
orzip
, used for the distribution package. count
-
(integer) Number of selected nodes using the distribution flavor and file type.
Examples
GET /_cluster/stats?human&pretty
The API returns the following response:
{
"_nodes" : {
"total" : 1,
"successful" : 1,
"failed" : 0
},
"cluster_uuid": "YjAvIhsCQ9CbjWZb2qJw3Q",
"cluster_name": "opensearch",
"timestamp":<PHONE_NUMBER>515,
"status": "green",
"indices": {
"count": 1,
"shards": {
"total": 5,
"primaries": 5,
"replication": 0,
"index": {
"shards": {
"min": 5,
"max": 5,
"avg": 5
},
"primaries": {
"min": 5,
"max": 5,
"avg": 5
},
"replication": {
"min": 0,
"max": 0,
"avg": 0
}
}
},
"docs": {
"count": 10,
"deleted": 0
},
"store": {
"size": "16.2kb",
"size_in_bytes": 16684,
"reserved": "0b",
"reserved_in_bytes": 0
},
"fielddata": {
"memory_size": "0b",
"memory_size_in_bytes": 0,
"evictions": 0
},
"query_cache": {
"memory_size": "0b",
"memory_size_in_bytes": 0,
"total_count": 0,
"hit_count": 0,
"miss_count": 0,
"cache_size": 0,
"cache_count": 0,
"evictions": 0
},
"completion": {
"size": "0b",
"size_in_bytes": 0
},
"segments": {
"count": 4,
"memory": "8.6kb",
"memory_in_bytes": 8898,
"terms_memory": "6.3kb",
"terms_memory_in_bytes": 6522,
"stored_fields_memory": "1.2kb",
"stored_fields_memory_in_bytes": 1248,
"term_vectors_memory": "0b",
"term_vectors_memory_in_bytes": 0,
"norms_memory": "384b",
"norms_memory_in_bytes": 384,
"points_memory" : "0b",
"points_memory_in_bytes" : 0,
"doc_values_memory": "744b",
"doc_values_memory_in_bytes": 744,
"index_writer_memory": "0b",
"index_writer_memory_in_bytes": 0,
"version_map_memory": "0b",
"version_map_memory_in_bytes": 0,
"fixed_bit_set": "0b",
"fixed_bit_set_memory_in_bytes": 0,
"max_unsafe_auto_id_timestamp" : -9223372036854775808,
"file_sizes": {}
},
"mappings": {
"field_types": []
},
"analysis": {
"char_filter_types": [],
"tokenizer_types": [],
"filter_types": [],
"analyzer_types": [],
"built_in_char_filters": [],
"built_in_tokenizers": [],
"built_in_filters": [],
"built_in_analyzers": []
}
},
"nodes": {
"count": {
"total": 1,
"data": 1,
"coordinating_only": 0,
"master": 1,
"ingest": 1,
"remote_cluster_client": 1
},
"versions": [
"1.0.0"
],
"os": {
"available_processors": 8,
"allocated_processors": 8,
"names": [
{
"name": "Mac OS X",
"count": 1
}
],
"pretty_names": [
{
"pretty_name": "Mac OS X",
"count": 1
}
],
"mem" : {
"total" : "16gb",
"total_in_bytes" :<PHONE_NUMBER>4,
"free" : "78.1mb",
"free_in_bytes" : 81960960,
"used" : "15.9gb",
"used_in_bytes" :<PHONE_NUMBER>4,
"free_percent" : 0,
"used_percent" : 100
}
},
"process": {
"cpu": {
"percent": 9
},
"open_file_descriptors": {
"min": 268,
"max": 268,
"avg": 268
}
},
"jvm": {
"max_uptime": "13.7s",
"max_uptime_in_millis": 13737,
"versions": [
{
"version": "12",
"vm_name": "OpenJDK 64-Bit Server VM",
"vm_version": "12+33",
"vm_vendor": "Oracle Corporation",
"bundled_jdk": true,
"using_bundled_jdk": true,
"count": 1
}
],
"mem": {
"heap_used": "57.5mb",
"heap_used_in_bytes": 60312664,
"heap_max": "989.8mb",
"heap_max_in_bytes":<PHONE_NUMBER>
},
"threads": 90
},
"fs": {
"total": "200.6gb",
"total_in_bytes":<PHONE_NUMBER>28,
"free": "32.6gb",
"free_in_bytes":<PHONE_NUMBER>2,
"available": "32.4gb",
"available_in_bytes":<PHONE_NUMBER>2
},
"plugins": [
{
"name": "analysis-icu",
"version": "1.0.0",
"description": "The ICU Analysis plugin integrates Lucene ICU module into opensearch, adding ICU relates analysis components.",
"classname": "org.opensearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
},
...
],
"ingest": {
"number_of_pipelines" : 1,
"processor_stats": {
...
}
},
"network_types": {
...
},
"discovery_types": {
...
},
"packaging_types": [
{
...
}
]
}
}
This API can be restricted to a subset of the nodes using node filters:
GET /_cluster/stats/nodes/node1,node*,master:false
Cluster update settings API
Updates cluster-wide settings.
Request
PUT /_cluster/settings
Description
With specifications in the request body, this API call can update cluster settings. Updates to settings can be persistent, meaning they apply across restarts, or transient, where they don’t survive a full cluster restart.
You can reset persistent or transient settings by assigning a null
value. If a
transient setting is reset, the first one of these values that is defined is
applied:
-
the persistent setting
-
the setting in the configuration file
-
the default value.
The order of precedence for cluster settings is:
-
transient cluster settings
-
persistent cluster settings
-
settings in the
opensearch.yml
configuration file.
It’s best to set all cluster-wide settings with the settings
API and use the
opensearch.yml
file only for local configurations. This way you can be sure that
the setting is the same on all nodes. If, on the other hand, you define different
settings on different nodes by accident using the configuration file, it is very
difficult to notice these discrepancies.
Query parameters
flat_settings
-
(Optional, Boolean) If
true
, returns settings in flat format. Defaults tofalse
. include_defaults
-
(Optional, Boolean) If
true
, returns all default cluster settings. Defaults tofalse
. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Examples
An example of a persistent update:
PUT /_cluster/settings
{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}
An example of a transient update:
PUT /_cluster/settings?flat_settings=true
{
"transient" : {
"indices.recovery.max_bytes_per_sec" : "20mb"
}
}
The response to an update returns the changed setting, as in this response to the transient example:
{
...
"persistent" : { },
"transient" : {
"indices.recovery.max_bytes_per_sec" : "20mb"
}
}
This example resets a setting:
PUT /_cluster/settings
{
"transient" : {
"indices.recovery.max_bytes_per_sec" : null
}
}
The response does not include settings that have been reset:
{
...
"persistent" : {},
"transient" : {}
}
You can also reset settings using wildcards. For example, to reset
all dynamic indices.recovery
settings:
PUT /_cluster/settings
{
"transient" : {
"indices.recovery.*" : null
}
}
Nodes feature usage API
Returns information on the usage of features.
Request
GET /_nodes/usage
GET /_nodes/<node_id>/usage
GET /_nodes/usage/<metric>
GET /_nodes/<node_id>/usage/<metric>
Description
The cluster nodes usage API allows you to retrieve information on the usage of features for each node. All the nodes selective options are explained here.
Path parameters
<metric>
-
(Optional, string) Limits the information returned to the specific metrics. A comma-separated list of the following options:
_all
-
Returns all stats.
rest_actions
-
Returns the REST actions classname with a count of the number of times that action has been called on the node.
<node_id>
-
(Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Query parameters
master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Examples
Rest action example:
GET _nodes/usage
The API returns the following response:
{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"timestamp":<PHONE_NUMBER>812, (1)
"since":<PHONE_NUMBER>606, (2)
"rest_actions": {
"nodes_usage_action": 1,
"create_index_action": 1,
"document_get_action": 1,
"search_action": 19, (3)
"nodes_info_action": 36
},
"aggregations": {
...
}
}
}
}
-
Timestamp for when this nodes usage request was performed.
-
Timestamp for when the usage information recording was started. This is equivalent to the time that the node was started.
-
Search action has been called 19 times for this node.
Nodes hot threads API
Returns the hot threads on each selected node in the cluster.
Request
GET /_nodes/hot_threads
GET /_nodes/<node_id>/hot_threads
Description
This API yields a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of each node’s top hot threads.
Path parameters
<node_id>
-
(Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Query parameters
ignore_idle_threads
-
(Optional, Boolean) If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out. Defaults to true.
interval
-
(Optional, time units) The interval to do the second sampling of threads. Defaults to
500ms
. snapshots
-
(Optional, integer) Number of samples of thread stacktrace. Defaults to
10
. threads
-
(Optional, integer) Specifies the number of hot threads to provide information for. Defaults to
3
. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. type
-
(Optional, string) The type to sample. Available options are
block
,cpu
, andwait
. Defaults tocpu
.
Examples
GET /_nodes/hot_threads
GET /_nodes/nodeId1,nodeId2/hot_threads
Nodes info API
Returns cluster nodes information.
Request
GET /_nodes
GET /_nodes/<node_id>
GET /_nodes/<metric>
GET /_nodes/<node_id>/<metric>
Description
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 here.
By default, it returns all attributes and core settings for a node.
Path parameters
<metric>
-
(Optional, string) Limits the information returned to the specific metrics. Supports a comma-separated list, such as
http,ingest
.Valid values for
<metric>
http
-
HTTP connection information.
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.
plugins
-
Details about the installed plugins and modules per node. The following information is available for each plugin and module:
-
name
: plugin name -
version
: version of OpenSearch 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.
settings
-
Lists all node settings in use as defined in the
opensearch.yml
file. 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.
<node_id>
-
(Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Response body
build_hash
-
Short hash of the last git commit in this release.
host
-
The node’s host name.
ip
-
The node’s IP address.
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 settings.
total_indexing_buffer_in_bytes
-
Same as
total_indexing_buffer
, but expressed in bytes. transport_address
-
Host and port where transport HTTP connections are accepted.
version
-
OpenSearch version running on this node.
The os
flag can be set to retrieve information that concern the operating
system:
os.refresh_interval_in_millis
-
Refresh interval for the OS statistics
os.name
-
Name of the operating system (ex: Linux, Windows, Mac OS X)
os.arch
-
Name of the JVM architecture (ex: amd64, x86)
os.version
-
Version of the operating system
os.available_processors
-
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
node.processors
setting of a node and defaults to the number of processors reported by the OS.
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
process.id
-
Process identifier (PID)
process.mlockall
-
Indicates if the process address space has been successfully locked in memory
Query parameters
flat_settings
-
(Optional, Boolean) If
true
, returns settings in flat format. Defaults tofalse
. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Examples
# return just process
GET /_nodes/process
# 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
The _all
flag can be set to return all the information - or you can omit it.
Example for plugins metric
If plugins
is specified, the result will contain details about the installed
plugins and modules:
GET /_nodes/plugins
The API returns the following response:
{
"_nodes": ...
"cluster_name": "opensearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.opensearch.org",
"ip": "192.168.17",
"version": "{version}",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU module into opensearch, adding ICU relates analysis components.",
"classname": "org.opensearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for OpenSearch",
"classname": "org.opensearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}
Example for ingest metric
If ingest
is specified, the response contains details about the available
processors per node:
GET /_nodes/ingest
The API returns the following response:
{
"_nodes": ...
"cluster_name": "opensearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.opensearch.org",
"ip": "192.168.17",
"version": "{version}",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [],
"attributes": {},
"ingest": {
"processors": [
{
"type": "date"
},
{
"type": "uppercase"
},
{
"type": "set"
},
{
"type": "lowercase"
},
{
"type": "gsub"
},
{
"type": "convert"
},
{
"type": "remove"
},
{
"type": "fail"
},
{
"type": "foreach"
},
{
"type": "split"
},
{
"type": "trim"
},
{
"type": "rename"
},
{
"type": "join"
},
{
"type": "append"
}
]
}
}
}
}
Nodes reload secure settings API
Reloads the keystore on nodes in the cluster.
Request
POST /_nodes/reload_secure_settings
POST /_nodes/<node_id>/reload_secure_settings
Description
Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.
When the OpenSearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that all nodes' keystores are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific OpenSearch keystore password.
Path parameters
<node_id>
-
(Optional, string) The names of particular nodes in the cluster to target. For example,
nodeId1,nodeId2
. For node selection options, see Node specification.
|
Note
|
OpenSearch requires consistent secure settings across the cluster nodes, but this consistency is not enforced. Hence, reloading specific nodes is not standard. It is justifiable only when retrying failed reload operations. |
Request body
secure_settings_password
-
(Optional, string) The password for the OpenSearch keystore.
Examples
The following examples assume a common password for the OpenSearch keystore on every node of the cluster:
POST _nodes/reload_secure_settings
{
"secure_settings_password":"s3cr3t"
}
POST _nodes/nodeId1,nodeId2/reload_secure_settings
{
"secure_settings_password":"s3cr3t"
}
The response contains the nodes
object, which is a map, keyed by the
node id. Each value has the node name
and an optional reload_exception
field. The reload_exception
field is a serialization of the exception
that was thrown during the reload process, if any.
{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"name": "node-0"
}
}
}
Nodes stats API
Returns cluster nodes statistics.
Request
GET /_nodes/stats
GET /_nodes/<node_id>/stats
GET/_nodes/stats/<metric>
GET/_nodes/<node_id>/stats/<metric>
GET /_nodes/stats/<metric>/<index_metric>
GET /_nodes/<node_id>/stats/<metric>/<index_metric>
Description
You can use the cluster nodes stats API to retrieve statistics for nodes in a cluster.
All the nodes selective options are explained here.
By default, all stats are returned. You can limit the returned information by using metrics.
Path parameters
<metric>
-
(Optional, string) Limits the information returned to the specific metrics. A comma-separated list of the following options:
adaptive_selection
-
Statistics about adaptive replica selection.
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.
indexing_pressure
-
Statistics about the node’s indexing load and related rejections.
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 ifindices
(orall
) metric is specified. Supported metrics are:-
completion
-
docs
-
fielddata
-
flush
-
get
-
indexing
-
merge
-
query_cache
-
recovery
-
refresh
-
request_cache
-
search
-
segments
-
store
-
translog
-
warmer
-
<node_id>
-
(Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Query parameters
completion_fields
-
(Optional, string) Comma-separated list or wildcard expressions of fields to include in
fielddata
andsuggest
statistics. fielddata_fields
-
(Optional, string) Comma-separated list or wildcard expressions of fields to include in
fielddata
statistics. fields
-
(Optional, string) Comma-separated list or wildcard expressions of fields to include in the statistics.
Used as the default list unless a specific field list is provided in the
completion_fields
orfielddata_fields
parameters. groups
-
(Optional, string) Comma-separated list of search groups to include in the
search
statistics. level
-
(Optional, string) Indicates whether statistics are aggregated at the cluster, index, or shard level.
Valid values are:
-
cluster
-
indices
-
shards
-
types
-
(Optional, string) A comma-separated list of document types for the
indexing
index metric. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. 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 tofalse
.
Response body
_nodes
-
(object) Contains statistics about the number of nodes selected by the request.
Properties of
_nodes
total
-
(integer) Total number of nodes selected by the request.
successful
-
(integer) Number of nodes that responded successfully to the request.
failed
-
(integer) Number of nodes that rejected the request or failed to respond. If this value is not
0
, a reason for the rejection or failure is included in the response.
cluster_name
-
(string) Name of the cluster. Based on the Cluster name setting setting.
nodes
-
(object) Contains statistics for the nodes selected by the request.
Properties of
nodes
<node_id>
-
(object) Contains statistics for the node.
Properties of
<node_id>
timestamp
-
(integer) Time the node stats were collected for this response. Recorded in milliseconds since the Unix Epoch.
name
-
(string) Human-readable identifier for the node. Based on the Node name setting setting.
transport_address
-
(string) Host and port for the transport layer, used for internal communication between nodes in a cluster.
host
-
(string) Network host for the node, based on the Network host setting setting.
ip
-
(string) IP address and port for the node.
roles
-
(array of strings) Roles assigned to the node. See Node.
attributes
-
(object) Contains a list of attributes for the node.
indices
-
(object) Contains statistics about indices with shards assigned to the node.
Properties of
indices
docs
-
(object) Contains statistics about documents across all primary shards assigned to the node.
Properties of
docs
count
-
(integer) The number of documents as reported by Lucene. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment.
deleted
-
(integer) The number of deleted documents as reported by Lucene, which may be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, OpenSearch creates extra deleted documents to internally track the recent history of operations on a shard.
store
-
(object) Contains statistics about the size of shards assigned to the node.
Properties of
store
size
-
(byte value) Total size of all shards assigned to the node.
size_in_bytes
-
(integer) Total size, in bytes, of all shards assigned to the node.
reserved
-
(byte value) A prediction of how much larger the shard stores on this node will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities. A value of
-1b
indicates that this is not available. reserved_in_bytes
-
(integer) A prediction, in bytes, of how much larger the shard stores on this node will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities. A value of
-1
indicates that this is not available.
indexing
-
(object) Contains statistics about indexing operations for the node.
Properties of
indexing
index_total
-
(integer) Total number of indexing operations.
index_time
-
(time value) Total time spent performing indexing operations.
index_time_in_millis
-
(integer) Total time in milliseconds spent performing indexing operations.
index_current
-
(integer) Number of indexing operations currently running.
index_failed
-
(integer) Number of failed indexing operations.
delete_total
-
(integer) Total number of deletion operations.
delete_time
-
(time value) Time spent performing deletion operations.
delete_time_in_millis
-
(integer) Time in milliseconds spent performing deletion operations.
delete_current
-
(integer) Number of deletion operations currently running.
noop_update_total
-
(integer) Total number of noop operations.
is_throttled
-
(Boolean) Number of times operations were throttled.
throttle_time
-
(time value) Total time spent throttling operations.
throttle_time_in_millis
-
(integer) Total time in milliseconds spent throttling operations.
get
-
(object) Contains statistics about get operations for the node.
Properties of
get
total
-
(integer) Total number of get operations.
getTime
-
(time value) Time spent performing get operations.
time_in_millis
-
(integer) Time in milliseconds spent performing get operations.
exists_total
-
(integer) Total number of successful get operations.
exists_time
-
(time value) Time spent performing successful get operations.
exists_time_in_millis
-
(integer) Time in milliseconds spent performing successful get operations.
missing_total
-
(integer) Total number of failed get operations.
missing_time
-
(time value) Time spent performing failed get operations.
missing_time_in_millis
-
(integer) Time in milliseconds spent performing failed get operations.
current
-
(integer) Number of get operations currently running.
search
-
(object) Contains statistics about search operations for the node.
Properties of
search
open_contexts
-
(integer) Number of open search contexts.
query_total
-
(integer) Total number of query operations.
query_time
-
(time value) Time spent performing query operations.
query_time_in_millis
-
(integer) Time in milliseconds spent performing query operations.
query_current
-
(integer) Number of query operations currently running.
fetch_total
-
(integer) Total number of fetch operations.
fetch_time
-
(time value) Time spent performing fetch operations.
fetch_time_in_millis
-
(integer) Time in milliseconds spent performing fetch operations.
fetch_current
-
(integer) Number of fetch operations currently running.
scroll_total
-
(integer) Total number of scroll operations.
scroll_time
-
(time value) Time spent performing scroll operations.
scroll_time_in_millis
-
(integer) Time in milliseconds spent performing scroll operations.
scroll_current
-
(integer) Number of scroll operations currently running.
suggest_total
-
(integer) Total number of suggest operations.
suggest_time
-
(time value) Time spent performing suggest operations.
suggest_time_in_millis
-
(integer) Time in milliseconds spent performing suggest operations.
suggest_current
-
(integer) Number of suggest operations currently running.
merges
-
(object) Contains statistics about merge operations for the node.
Properties of
merges
current
-
(integer) Number of merge operations currently running.
current_docs
-
(integer) Number of document merges currently running.
current_size
-
(byte value) Memory used performing current document merges.
current_size_in_bytes
-
(integer) Memory, in bytes, used performing current document merges.
total
-
(integer) Total number of merge operations.
total_time
-
(time value) Total time spent performing merge operations.
total_time_in_millis
-
(integer) Total time in milliseconds spent performing merge operations.
total_docs
-
(integer) Total number of merged documents.
total_size
-
(byte value) Total size of document merges.
total_size_in_bytes
-
(integer) Total size of document merges in bytes.
total_stopped_time
-
(time value) Total time spent stopping merge operations.
total_stopped_time_in_millis
-
(integer) Total time in milliseconds spent stopping merge operations.
total_throttled_time
-
(time value) Total time spent throttling merge operations.
total_throttled_time_in_millis
-
(integer) Total time in milliseconds spent throttling merge operations.
total_auto_throttle
-
(byte value) Size of automatically throttled merge operations.
total_auto_throttle_in_bytes
-
(integer) Size, in bytes, of automatically throttled merge operations.
refresh
-
(object) Contains statistics about refresh operations for the node.
Properties of
refresh
total
-
(integer) Total number of refresh operations.
total_time
-
(time value) Total time spent performing refresh operations.
total_time_in_millis
-
(integer) Total time in milliseconds spent performing refresh operations.
external_total
-
(integer) Total number of external refresh operations.
external_total_time
-
(time value) Total time spent performing external operations.
external_total_time_in_millis
-
(integer) Total time in milliseconds spent performing external operations.
listeners
-
(integer) Number of refresh listeners.
flush
-
(object) Contains statistics about flush operations for the node.
Properties of
flush
total
-
(integer) Number of flush operations.
periodic
-
(integer) Number of flush periodic operations.
total_time
-
(time value) Total time spent performing flush operations.
total_time_in_millis
-
(integer) Total time in milliseconds spent performing flush operations.
warmer
-
(object) Contains statistics about index warming operations for the node.
Properties of
warmer
current
-
(integer) Number of active index warmers.
total
-
(integer) Total number of index warmers.
total_time
-
(time value) Total time spent performing index warming operations.
total_time_in_millis
-
(integer) Total time in milliseconds spent performing index warming operations.
query_cache
-
(object) Contains statistics about the query cache across all shards assigned to the node.
Properties of
query_cache
memory_size
-
(byte value) Total amount of memory used for the query cache across all shards assigned to the node.
memory_size_in_bytes
-
(integer) Total amount of memory, in bytes, used for the query cache across all shards assigned to the node.
total_count
-
(integer) Total count of hits, misses, and cached queries in the query cache.
hit_count
-
(integer) Number of query cache hits.
miss_count
-
(integer) Number of query cache misses.
cache_size
-
(integer) Size, in bytes, of the query cache.
cache_count
-
(integer) Count of queries in the query cache.
evictions
-
(integer) Number of query cache evictions.
fielddata
-
(object) Contains statistics about the field data cache across all shards assigned to the node.
Properties of
fielddata
memory_size
-
(byte value) Total amount of memory used for the field data cache across all shards assigned to the node.
memory_size_in_bytes
-
(integer) Total amount of memory, in bytes, used for the field data cache across all shards assigned to the node.
evictions
-
(integer) Number of fielddata evictions.
completion
-
(object) Contains statistics about completions across all shards assigned to the node.
Properties of
completion
size
-
(byte value) Total amount of memory used for completion across all shards assigned to the node.
size_in_bytes
-
(integer) Total amount of memory, in bytes, used for completion across all shards assigned to the node.
segments
-
(object) Contains statistics about segments across all shards assigned to the node.
Properties of
segments
count
-
(integer) Number of segments.
memory
-
(byte value) Total amount of memory used for segments across all shards assigned to the node.
memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for segments across all shards assigned to the node.
terms_memory
-
(byte value) Total amount of memory used for terms across all shards assigned to the node.
terms_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for terms across all shards assigned to the node.
stored_fields_memory
-
(byte value) Total amount of memory used for stored fields across all shards assigned to the node.
stored_fields_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for stored fields across all shards assigned to the node.
term_vectors_memory
-
(byte value) Total amount of memory used for term vectors across all shards assigned to the node.
term_vectors_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for term vectors across all shards assigned to the node.
norms_memory
-
(byte value) Total amount of memory used for normalization factors across all shards assigned to the node.
norms_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for normalization factors across all shards assigned to the node.
points_memory
-
(byte value) Total amount of memory used for points across all shards assigned to the node.
points_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for points across all shards assigned to the node.
doc_values_memory
-
(byte value) Total amount of memory used for doc values across all shards assigned to the node.
doc_values_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used for doc values across all shards assigned to the node.
index_writer_memory
-
(byte value) Total amount of memory used by all index writers across all shards assigned to the node.
index_writer_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used by all index writers across all shards assigned to the node.
version_map_memory
-
(byte value) Total amount of memory used by all version maps across all shards assigned to the node.
version_map_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used by all version maps across all shards assigned to the node.
fixed_bit_set
-
(byte value) Total amount of memory used by fixed bit sets across all shards assigned to the node.
Fixed bit sets are used for nested object field types and type filters for join fields.
fixed_bit_set_memory_in_bytes
-
(integer) Total amount of memory, in bytes, used by fixed bit sets across all shards assigned to the node.
Fixed bit sets are used for nested object field types and type filters for join fields.
max_unsafe_auto_id_timestamp
-
(integer) Time of the most recently retried indexing request. Recorded in milliseconds since the Unix Epoch.
file_sizes
-
(object) Contains statistics about the size of the segment file.
Properties of
file_sizes
size
-
(byte value) Size of the segment file.
size_in_bytes
-
(integer) Size, in bytes, of the segment file.
description
-
(string) Description of the segment file.
translog
-
(object) Contains statistics about transaction log operations for the node.
Properties of
translog
operations
-
(integer) Number of transaction log operations.
size
-
(byte value) Size of the transaction log.
size_in_bytes
-
(integer) Size, in bytes, of the transaction log.
uncommitted_operations
-
(integer) Number of uncommitted transaction log operations.
uncommitted_size
-
(byte value) Size of uncommitted transaction log operations.
uncommitted_size_in_bytes
-
(integer) Size, in bytes, of uncommitted transaction log operations.
earliest_last_modified_age
-
(integer) Earliest last modified age for the transaction log.
request_cache
-
(object) Contains statistics about the request cache across all shards assigned to the node.
Properties of
request_cache
memory_size
-
(byte value) Memory used by the request cache.
memory_size_in_bytes
-
(integer) Memory, in bytes, used by the request cache.
evictions
-
(integer) Number of request cache operations.
hit_count
-
(integer) Number of request cache hits.
miss_count
-
(integer) Number of request cache misses.
recovery
-
(object) Contains statistics about recovery operations for the node.
Properties of
recovery
current_as_source
-
(integer) Number of recoveries that used an index shard as a source.
current_as_target
-
(integer) Number of recoveries that used an index shard as a target.
throttle_time
-
(time value) Time by which recovery operations were delayed due to throttling.
throttle_time_in_millis
-
(integer) Time in milliseconds recovery operations were delayed due to throttling.
os
-
(object) Contains statistics about the operating system for the node.
Properties of
os
timestamp
-
(integer) Last time the operating system statistics were refreshed. Recorded in milliseconds since the Unix Epoch.
cpu
-
(object) Contains statistics about CPU usage for the node.
Properties of
cpu
percent
-
(integer) Recent CPU usage for the whole system, or
-1
if not supported. load_average
-
(object) Contains statistics about load averages on the system.
Properties of
load_average
1m
-
(float) One-minute load average on the system (field is not present if one-minute load average is not available).
5m
-
(float) Five-minute load average on the system (field is not present if five-minute load average is not available).
15m
-
(float) Fifteen-minute load average on the system (field is not present if fifteen-minute load average is not available).
mem
-
(object) Contains statistics about memory usage for the node.
Properties of
mem
total
-
(byte value) Total amount of physical memory.
total_in_bytes
-
(integer) Total amount of physical memory in bytes.
free
-
(byte value) Amount of free physical memory.
free_in_bytes
-
(integer) Amount of free physical memory in bytes.
used
-
(byte value) Amount of used physical memory.
used_in_bytes
-
(integer) Amount of used physical memory in bytes.
free_percent
-
(integer) Percentage of free memory.
used_percent
-
(integer) Percentage of used memory.
swap
-
(object) Contains statistics about swap space for the node.
Properties of
swap
total
-
(byte value) Total amount of swap space.
total_in_bytes
-
(integer) Total amount of swap space in bytes.
free
-
(byte value) Amount of free swap space.
free_in_bytes
-
(integer) Amount of free swap space in bytes.
used
-
(byte value) Amount of used swap space.
used_in_bytes
-
(integer) Amount of used swap space in bytes.
cgroup
(Linux only)-
(object) Contains cgroup statistics for the node.
NoteFor the cgroup stats to be visible, cgroups must be compiled into the kernel, the cpu
andcpuacct
cgroup subsystems must be configured and stats must be readable from/sys/fs/cgroup/cpu
and/sys/fs/cgroup/cpuacct
.Properties of
cgroup
cpuacct
(Linux only)-
(object) Contains statistics about
cpuacct
control group for the node.Properties of
cpuacct
control_group
(Linux only)-
(string) The
cpuacct
control group to which the OpenSearch process belongs. usage_nanos
(Linux only)-
(integer) The total CPU time (in nanoseconds) consumed by all tasks in the same cgroup as the OpenSearch process.
cpu
(Linux only)-
(object) Contains statistics about
cpu
control group for the node.Properties of
cpu
control_group
(Linux only)-
(string) The
cpu
control group to which the OpenSearch process belongs. cfs_period_micros
(Linux only)-
(integer) The period of time (in microseconds) for how regularly all tasks in the same cgroup as the OpenSearch process should have their access to CPU resources reallocated.
cfs_quota_micros
(Linux only)-
(integer) The total amount of time (in microseconds) for which all tasks in the same cgroup as the OpenSearch process can run during one period
cfs_period_micros
. stat
(Linux only)-
(object) Contains CPU statistics for the node.
Properties of
stat
number_of_elapsed_periods
(Linux only)-
(integer) The number of reporting periods (as specified by
cfs_period_micros
) that have elapsed. number_of_times_throttled
(Linux only)-
(integer) The number of times all tasks in the same cgroup as the OpenSearch process have been throttled.
time_throttled_nanos
(Linux only)-
(integer) The total amount of time (in nanoseconds) for which all tasks in the same cgroup as the OpenSearch process have been throttled.
memory
(Linux only)-
(object) Contains statistics about the
memory
control group for the node.Properties of
memory
control_group
(Linux only)-
(string) The
memory
control group to which the OpenSearch process belongs. limit_in_bytes
(Linux only)-
(string) The maximum amount of user memory (including file cache) allowed for all tasks in the same cgroup as the OpenSearch 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 along
almost certainly means no limit has been set for the cgroup. usage_in_bytes
(Linux only)-
(string) The total current memory usage by processes in the cgroup (in bytes) by all tasks in the same cgroup as the OpenSearch process. This value is stored as a string for consistency with
limit_in_bytes
.
process
-
(object) Contains process statistics for the node.
Properties of
process
timestamp
-
(integer) Last time the statistics were refreshed. Recorded in milliseconds since the Unix Epoch.
open_file_descriptors
-
(integer) Number of opened file descriptors associated with the current or
-1
if not supported. max_file_descriptors
-
(integer) Maximum number of file descriptors allowed on the system, or
-1
if not supported. cpu
-
(object) Contains CPU statistics for the node.
Properties of
cpu
percent
-
(integer) CPU usage in percent, or
-1
if not known at the time the stats are computed. total
-
(time value) CPU time used by the process on which the Java virtual machine is running.
total_in_millis
-
(integer) CPU time (in milliseconds) used by the process on which the Java virtual machine is running, or
-1
if not supported.
mem
-
(object) Contains virtual memory statistics for the node.
Properties of
mem
total_virtual
-
(byte value) Size of virtual memory that is guaranteed to be available to the running process.
total_virtual_in_bytes
-
(integer) Size in bytes of virtual memory that is guaranteed to be available to the running process.
jvm
-
(object) Contains Java Virtual Machine (JVM) statistics for the node.
Properties of
jvm
timestamp
-
(integer) Last time JVM statistics were refreshed.
uptime
-
(time value) JVM uptime.
uptime_in_millis
-
(integer) JVM uptime in milliseconds.
mem
-
(object) Contains JVM memory usage statistics for the node.
Properties of
mem
heap_used
-
(byte value) Memory currently in use by the heap.
heap_used_in_bytes
-
(integer) Memory, in bytes, currently in use by the heap.
heap_used_percent
-
(integer) Percentage of memory currently in use by the heap.
heap_committed
-
(byte value) Amount of memory available for use by the heap.
heap_committed_in_bytes
-
(integer) Amount of memory, in bytes, available for use by the heap.
heap_max
-
(byte value) Maximum amount of memory available for use by the heap.
heap_max_in_bytes
-
(integer) Maximum amount of memory, in bytes, available for use by the heap.
non_heap_used
-
(byte value) Non-heap memory used.
non_heap_used_in_bytes
-
(integer) Non-heap memory used, in bytes.
non_heap_committed
-
(byte value) Amount of non-heap memory available.
non_heap_committed_in_bytes
-
(integer) Amount of non-heap memory available, in bytes.
pools
-
(object) Contains statistics about heap memory usage for the node.
Properties of
pools
young
-
(object) Contains statistics about memory usage by the young generation heap for the node.
Properties of
young
used
-
(byte value) Memory used by the young generation heap.
used_in_bytes
-
(integer) Memory, in bytes, used by the young generation heap.
max
-
(byte value) Maximum amount of memory available for use by the young generation heap.
max_in_bytes
-
(integer) Maximum amount of memory, in bytes, available for use by the young generation heap.
peak_used
-
(byte value) Largest amount of memory historically used by the young generation heap.
peak_used_in_bytes
-
(integer) Largest amount of memory, in bytes, historically used by the young generation heap.
peak_max
-
(byte value) Largest amount of memory historically used by the young generation heap.
peak_max_in_bytes
-
(integer) Largest amount of memory, in bytes, historically used by the young generation heap.
survivor
-
(object) Contains statistics about memory usage by the survivor space for the node.
Properties of
survivor
used
-
(byte value) Memory used by the survivor space.
used_in_bytes
-
(integer) Memory, in bytes, used by the survivor space.
max
-
(byte value) Maximum amount of memory available for use by the survivor space.
max_in_bytes
-
(integer) Maximum amount of memory, in bytes, available for use by the survivor space.
peak_used
-
(byte value) Largest amount of memory historically used by the survivor space.
peak_used_in_bytes
-
(integer) Largest amount of memory, in bytes, historically used by the survivor space.
peak_max
-
(byte value) Largest amount of memory historically used by the survivor space.
peak_max_in_bytes
-
(integer) Largest amount of memory, in bytes, historically used by the survivor space.
old
-
(object) Contains statistics about memory usage by the old generation heap for the node.
Properties of
old
used
-
(byte value) Memory used by the old generation heap.
used_in_bytes
-
(integer) Memory, in bytes, used by the old generation heap.
max
-
(byte value) Maximum amount of memory available for use by the old generation heap.
max_in_bytes
-
(integer) Maximum amount of memory, in bytes, available for use by the old generation heap.
peak_used
-
(byte value) Largest amount of memory historically used by the old generation heap.
peak_used_in_bytes
-
(integer) Largest amount of memory, in bytes, historically used by the old generation heap.
peak_max
-
(byte value) Highest memory limit historically available for use by the old generation heap.
peak_max_in_bytes
-
(integer) Highest memory limit, in bytes, historically available for use by the old generation heap.
threads
-
(object) Contains statistics about JVM thread usage for the node.
Properties of
threads
count
-
(integer) Number of active threads in use by JVM.
peak_count
-
(integer) Highest number of threads used by JVM.
gc
-
(object) Contains statistics about JVM garbage collectors for the node.
Properties of
gc
collectors
-
(object) Contains statistics about JVM garbage collectors for the node.
Properties of
collectors
young
-
(object) Contains statistics about JVM garbage collectors that collect young generation objects for the node.
Properties of
young
collection_count
-
(integer) Number of JVM garbage collectors that collect young generation objects.
collection_time
-
(time value) Total time spent by JVM collecting young generation objects.
collection_time_in_millis
-
(integer) Total time in milliseconds spent by JVM collecting young generation objects.
old
-
(object) Contains statistics about JVM garbage collectors that collect old generation objects for the node.
Properties of
old
collection_count
-
(integer) Number of JVM garbage collectors that collect old generation objects.
collection_time
-
(time value) Total time spent by JVM collecting old generation objects.
collection_time_in_millis
-
(integer) Total time in milliseconds spent by JVM collecting old generation objects.
buffer_pools
-
(object) Contains statistics about JVM buffer pools for the node.
Properties of
buffer_pools
mapped
-
(object) Contains statistics about mapped JVM buffer pools for the node.
Properties of
mapped
count
-
(integer) Number of mapped buffer pools.
used
-
(byte value) Size of mapped buffer pools.
used_in_bytes
-
(integer) Size, in bytes, of mapped buffer pools.
total_capacity
-
(byte value) Total capacity of mapped buffer pools.
total_capacity_in_bytes
-
(integer) Total capacity, in bytes, of mapped buffer pools.
direct
-
(object) Contains statistics about direct JVM buffer pools for the node.
Properties of
direct
count
-
(integer) Number of direct buffer pools.
used
-
(byte value) Size of direct buffer pools.
used_in_bytes
-
(integer) Size, in bytes, of direct buffer pools.
total_capacity
-
(byte value) Total capacity of direct buffer pools.
total_capacity_in_bytes
-
(integer) Total capacity, in bytes, of direct buffer pools.
classes
-
(object) Contains statistics about classes loaded by JVM for the node.
Properties of
classes
current_loaded_count
-
(integer) Number of classes currently loaded by JVM.
total_loaded_count
-
(integer) Total number of classes loaded since the JVM started.
total_unloaded_count
-
(integer) Total number of classes unloaded since the JVM started.
thread_pool
-
(object) Contains thread pool statistics for the node
Properties of
thread_pool
<thread_pool_name>
-
(object) Contains statistics about the thread pool for the node.
Properties of
<thread_pool_name>
threads
-
(integer) Number of threads in the thread pool.
queue
-
(integer) Number of tasks in queue for the thread pool.
active
-
(integer) Number of active threads in the thread pool.
rejected
-
(integer) Number of tasks rejected by the thread pool executor.
largest
-
(integer) Highest number of active threads in the thread pool.
completed
-
(integer) Number of tasks completed by the thread pool executor.
fs
-
(object) Contains file store statistics for the node.
Properties of
fs
timestamp
-
(integer) Last time the file stores statistics were refreshed. Recorded in milliseconds since the Unix Epoch.
total
-
(object) Contains statistics for all file stores of the node.
Properties of
total
total
-
(byte value) Total size of all file stores.
total_in_bytes
-
(integer) Total size (in bytes) of all file stores.
free
-
(byte value) Total unallocated disk space in all file stores.
free_in_bytes
-
(integer) Total number of unallocated bytes in all file stores.
available
-
(byte value) Total disk space available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than
free
. This is the actual amount of free disk space the OpenSearch node can utilise. available_in_bytes
-
(integer) 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
free_in_bytes
. This is the actual amount of free disk space the OpenSearch node can utilise.
data
-
(array of objects) List of all file stores.
Properties of
data
path
-
(string) Path to the file store.
mount
-
(string) Mount point of the file store (ex: /dev/sda2).
type
-
(string) Type of the file store (ex: ext4).
total
-
(byte value) Total size of the file store.
total_in_bytes
-
(integer) Total size (in bytes) of the file store.
free
-
(byte value) Total amount of unallocated disk space in the file store.
free_in_bytes
-
(integer) Total number of unallocated bytes in the file store.
available
-
(byte value) Total amount of disk space available to this Java virtual machine on this file store.
available_in_bytes
-
(integer) Total number of bytes available to this Java virtual machine on this file store.
io_stats
(Linux only)-
(objects) Contains I/O statistics for the node.
Properties of
io_stats
devices
(Linux only)-
(array) Array of disk metrics for each device that is backing an OpenSearch data path. These disk metrics are probed periodically and averages between the last probe and the current probe are computed.
Properties of
devices
device_name
(Linux only)-
(string) The Linux device name.
operations
(Linux only)-
(integer) The total number of read and write operations for the device completed since starting OpenSearch.
read_operations
(Linux only)-
(integer) The total number of read operations for the device completed since starting OpenSearch.
write_operations
(Linux only)-
(integer) The total number of write operations for the device completed since starting OpenSearch.
read_kilobytes
(Linux only)-
(integer) The total number of kilobytes read for the device since starting OpenSearch.
write_kilobytes
(Linux only)-
(integer) The total number of kilobytes written for the device since starting OpenSearch.
operations
(Linux only)-
(integer) The total number of read and write operations across all devices used by OpenSearch completed since starting OpenSearch.
read_operations
(Linux only)-
(integer) The total number of read operations for across all devices used by OpenSearch completed since starting OpenSearch.
write_operations
(Linux only)-
(integer) The total number of write operations across all devices used by OpenSearch completed since starting OpenSearch.
read_kilobytes
(Linux only)-
(integer) The total number of kilobytes read across all devices used by OpenSearch since starting OpenSearch.
write_kilobytes
(Linux only)-
(integer) The total number of kilobytes written across all devices used by OpenSearch since starting OpenSearch.
transport
-
(object) Contains transport statistics for the node.
Properties of
transport
server_open
-
(integer) Current number of inbound TCP connections used for internal communication between nodes.
total_outbound_connections
-
(integer) The cumulative number of outbound transport connections that this node has opened since it started. Each transport connection may comprise multiple TCP connections but is only counted once in this statistic. Transport connections are typically long-lived so this statistic should remain constant in a stable cluster.
rx_count
-
(integer) Total number of RX (receive) packets received by the node during internal cluster communication.
rx_size
-
(byte value) Size of RX packets received by the node during internal cluster communication.
rx_size_in_bytes
-
(integer) Size, in bytes, of RX packets received by the node during internal cluster communication.
tx_count
-
(integer) Total number of TX (transmit) packets sent by the node during internal cluster communication.
tx_size
-
(byte value) Size of TX packets sent by the node during internal cluster communication.
tx_size_in_bytes
-
(integer) Size, in bytes, of TX packets sent by the node during internal cluster communication.
http
-
(object) Contains http statistics for the node.
Properties of
http
current_open
-
(integer) Current number of open HTTP connections for the node.
total_opened
-
(integer) Total number of HTTP connections opened for the node.
breakers
-
(object) Contains circuit breaker statistics for the node.
Properties of
breakers
<circuit_breaker_name>
-
(object) Contains statistics for the circuit breaker.
Properties of
<circuit_breaker_name>
limit_size_in_bytes
-
(integer) Memory limit, in bytes, for the circuit breaker.
limit_size
-
(byte value) Memory limit for the circuit breaker.
estimated_size_in_bytes
-
(integer) Estimated memory used, in bytes, for the operation.
estimated_size
-
(byte value) Estimated memory used for the operation.
overhead
-
(float) A constant that all estimates for the circuit breaker are multiplied with to calculate a final estimate.
tripped
-
(integer) Total number of times the circuit breaker has been triggered and prevented an out of memory error.
script
-
(object) Contains script statistics for the node.
Properties of
script
compilations
-
(integer) Total number of inline script compilations performed by the node.
cache_evictions
-
(integer) Total number of times the script cache has evicted old data.
compilation_limit_triggered
-
(integer) Total number of times the script compilation circuit breaker has limited inline script compilations.
discovery
-
(object) Contains node discovery statistics for the node.
Properties of
discovery
cluster_state_queue
-
(object) Contains statistics for the cluster state queue of the node.
Properties of
cluster_state_queue
total
-
(integer) Total number of cluster states in queue.
pending
-
(integer) Number of pending cluster states in queue.
committed
-
(integer) Number of committed cluster states in queue.
published_cluster_states
-
(object) Contains statistics for the published cluster states of the node.
Properties of
published_cluster_states
full_states
-
(integer) Number of published cluster states.
incompatible_diffs
-
(integer) Number of incompatible differences between published cluster states.
compatible_diffs
-
(integer) Number of compatible differences between published cluster states.
ingest
-
(object) Contains ingest statistics for the node.
Properties of
ingest
total
-
(object) Contains statistics about ingest operations for the node.
Properties of
total
count
-
(integer) Total number of documents ingested during the lifetime of this node.
time
-
(time value) Total time spent preprocessing ingest documents during the lifetime of this node.
time_in_millis
-
(integer) Total time, in milliseconds, spent preprocessing ingest documents during the lifetime of this node.
current
-
(integer) Total number of documents currently being ingested.
failed
-
(integer) Total number of failed ingest operations during the lifetime of this node.
pipelines
-
(object) Contains statistics about ingest pipelines for the node.
Properties of
pipelines
<pipeline_id>
-
(object) Contains statistics about the ingest pipeline.
Properties of
<pipeline_id>
count
-
(integer) Number of documents preprocessed by the ingest pipeline.
time
-
(time value) Total time spent preprocessing documents in the ingest pipeline.
time_in_millis
-
(integer) Total time, in milliseconds, spent preprocessing documents in the ingest pipeline.
failed
-
(integer) Total number of failed operations for the ingest pipeline.
processors
-
(array of objects) Contains statistics for the ingest processors for the ingest pipeline.
Properties of
processors
<processor>
-
(object) Contains statistics for the ingest processor.
Properties of
<processor>
count
-
(integer) Number of documents transformed by the processor.
time
-
(time value) Time spent by the processor transforming documents.
time_in_millis
-
(integer) Time, in milliseconds, spent by the processor transforming documents.
current
-
(integer) Number of documents currently being transformed by the processor.
failed
-
(integer) Number of failed operations for the processor.
indexing_pressure
-
(object) Contains indexing pressure statistics for the node.
Properties of
indexing_pressure
memory
-
(object) Contains statistics for memory consumption from indexing load.
Properties of
<memory>
current
-
(object) Contains statistics for current indexing load.
Properties of
<current>
combined_coordinating_and_primary
-
(byte value) Memory consumed by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.
combined_coordinating_and_primary_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.
coordinating
-
(byte value) Memory consumed by indexing requests in the coordinating stage.
coordinating_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating stage.
primary
-
(byte value) Memory consumed by indexing requests in the primary stage.
primary_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the primary stage.
replica
-
(byte value) Memory consumed by indexing requests in the replica stage.
replica_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the replica stage.
all
-
(byte value) Memory consumed by indexing requests in the coordinating, primary, or replica stage.
all_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating, primary, or replica stage.
total
-
(object) Contains statistics for the cumulative indexing load since the node started.
Properties of
<total>
combined_coordinating_and_primary
-
(byte value) Memory consumed by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.
combined_coordinating_and_primary_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.
coordinating
-
(byte value) Memory consumed by indexing requests in the coordinating stage.
coordinating_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating stage.
primary
-
(byte value) Memory consumed by indexing requests in the primary stage.
primary_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the primary stage.
replica
-
(byte value) Memory consumed by indexing requests in the replica stage.
replica_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the replica stage.
all
-
(byte value) Memory consumed by indexing requests in the coordinating, primary, or replica stage.
all_in_bytes
-
(integer) Memory consumed, in bytes, by indexing requests in the coordinating, primary, or replica stage.
coordinating_rejections
-
(integer) Number of indexing requests rejected in the coordinating stage.
primary_rejections
-
(integer) Number of indexing requests rejected in the primary stage.
replica_rejections
-
(integer) Number of indexing requests rejected in the replica stage.
limit
-
(byte value) Configured memory limit for the indexing requests. Replica requests have an automatic limit that is 1.5x this value.
limit_in_bytes
-
(integer) Configured memory limit, in bytes, for the indexing requests. Replica requests have an automatic limit that is 1.5x this value.
adaptive_selection
-
(object) Contains adaptive selection statistics for the node.
Properties of
adaptive_selection
outgoing_searches
-
(integer) The number of outstanding search requests from the node these stats are for to the keyed node.
avg_queue_size
-
(integer) The exponentially weighted moving average queue size of search requests on the keyed node.
avg_service_time
-
(time value) The exponentially weighted moving average service time of search requests on the keyed node.
avg_service_time_ns
-
(integer) The exponentially weighted moving average service time, in nanoseconds, of search requests on the keyed node.
avg_response_time
-
(time value) The exponentially weighted moving average response time of search requests on the keyed node.
avg_response_time_ns
-
(integer) The exponentially weighted moving average response time, in nanoseconds, of search requests on the keyed node.
rank
-
(string) The rank of this node; used for shard selection when routing search requests.
Examples
# return just indices
GET /_nodes/stats/indices
# return just os and process
GET /_nodes/stats/os,process
# return just process for node with IP address <IP_ADDRESS>
GET /_nodes/<IP_ADDRESS>/stats/process
All stats can be explicitly requested via /_nodes/stats/_all
or
/_nodes/stats?metric=_all
.
You can get information about indices stats on node
, indices
, or shards
level.
# Fielddata summarized by node
GET /_nodes/stats/indices/fielddata?fields=field1,field2
# Fielddata summarized by node and index
GET /_nodes/stats/indices/fielddata?level=indices&fields=field1,field2
# Fielddata summarized by node, index, and shard
GET /_nodes/stats/indices/fielddata?level=shards&fields=field1,field2
# You can use wildcards for field names
GET /_nodes/stats/indices/fielddata?fields=field*
You can get statistics about search groups for searches executed on this node.
# All groups with all stats
GET /_nodes/stats?groups=_all
# Some groups from just the indices stats
GET /_nodes/stats/indices?groups=foo,bar
Retrieve ingest statistics only
To return only ingest-related node statistics, set the <metric>
path
parameter to ingest
and use the
filter_path
query parameter.
GET /_nodes/stats/ingest?filter_path=nodes.*.ingest
You can use the metric
and filter_path
query parameters to get the same
response.
GET /_nodes/stats?metric=ingest&filter_path=nodes.*.ingest
To further refine the response, change the filter_path
value.
For example, the following request only returns ingest pipeline statistics.
GET /_nodes/stats?metric=ingest&filter_path=nodes.*.ingest.pipelines
Pending cluster tasks API
Returns cluster-level changes that have not yet been executed.
Request
GET /_cluster/pending_tasks
Description
The pending cluster tasks API returns a list of any cluster-level changes (e.g. create index, update mapping, allocate or fail shard) which have not yet been executed.
|
Note
|
This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the Task Management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API. |
Path parameters
local
-
(Optional, Boolean) If
true
, the request retrieves information from the local node only. Defaults tofalse
, which means information is retrieved from the master node. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
.
Response body
tasks
-
(object) A list of pending tasks.
insert_order
-
(integer) The number that represents when the task has been inserted into the task queue.
priority
-
(string) The priority of the pending task.
source
-
(string) A general description of the cluster task that may include a reason and origin.
time_in_queue_millis
-
(integer) The time expressed in milliseconds since the task is waiting for being performed.
time_in_queue
-
(string) The time since the task is waiting for being performed.
Examples
Usually the request will return an empty list as cluster-level changes are fast. However, if there are tasks queued up, the response will look similar like this:
{
"tasks": [
{
"insert_order": 101,
"priority": "URGENT",
"source": "create-index [foo_9], cause [api]",
"time_in_queue_millis": 86,
"time_in_queue": "86ms"
},
{
"insert_order": 46,
"priority": "HIGH",
"source": "shard-started ([foo_2][1], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING]), reason [after recovery from shard_store]",
"time_in_queue_millis": 842,
"time_in_queue": "842ms"
},
{
"insert_order": 45,
"priority": "HIGH",
"source": "shard-started ([foo_2][0], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING]), reason [after recovery from shard_store]",
"time_in_queue_millis": 858,
"time_in_queue": "858ms"
}
]
}
Remote cluster info API
Returns configured remote cluster information.
Request
GET /_remote/info
Description
The cluster remote info API allows you to retrieve all of the configured remote cluster information. It returns connection and endpoint information keyed by the configured remote cluster alias.
Response body
mode
-
Connection mode for the remote cluster. Returned values are
sniff
andproxy
. connected
-
True if there is at least one connection to the remote cluster.
initial_connect_timeout
-
The initial connect timeout for remote cluster connections.
Task management API
The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.
Returns information about the tasks currently executing in the cluster.
Request
GET /_tasks/<task_id>
GET /_tasks
Description
The task management API returns information about tasks currently executing on one or more nodes in the cluster.
Path parameters
<task_id>
-
(Optional, string) ID of the task to return (
node_id:task_number
).
Query parameters
actions
-
(Optional, string) Comma-separated list or wildcard expression of actions used to limit the request.
Omit this parameter to return all actions.
detailed
-
(Optional, Boolean) If
true
, the response includes detailed information about shard recoveries. Defaults tofalse
. group_by
-
(Optional, string) Key used to group tasks in the response.
Possible values are:
nodes
-
(Default) Node ID
parents
-
Parent task ID
none
-
Do not group tasks.
node_id
-
(Optional, string) Comma-separated list of node IDs or names used to limit returned information.
parent_task_id
-
(Optional, string) Parent task ID used to limit returned information.
To return all tasks, omit this parameter or use a value of
-1
. master_timeout
-
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. timeout
-
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to
30s
. wait_for_completion
-
(Optional, Boolean) If
true
, the request blocks until the operation is complete. Defaults tofalse
.
Response codes
404
(Missing resources)-
If
<task_id>
is specified but not found, this code indicates that there are no resources that match the request.
Examples
GET _tasks (1)
GET _tasks?nodes=nodeId1,nodeId2 (2)
GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* (3)
-
Retrieves all tasks currently running on all nodes in the cluster.
-
Retrieves all tasks running on nodes
nodeId1
andnodeId2
. See Node specification for more info about how to select individual nodes. -
Retrieves all cluster-related tasks running on nodes
nodeId1
andnodeId2
.
The API returns the following result:
{
"nodes" : {
"oTUltX4IQMOUUVeiohTt8A" : {
"name" : "H5dfFeA",
"transport_address" : "<IP_ADDRESS>:9300",
"host" : "<IP_ADDRESS>",
"ip" : "<IP_ADDRESS>:9300",
"tasks" : {
"oTUltX4IQMOUUVeiohTt8A:124" : {
"node" : "oTUltX4IQMOUUVeiohTt8A",
"id" : 124,
"type" : "direct",
"action" : "cluster:monitor/tasks/lists[n]",
"start_time_in_millis" :<PHONE_NUMBER>904,
"running_time_in_nanos" : 47402,
"cancellable" : false,
"parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
},
"oTUltX4IQMOUUVeiohTt8A:123" : {
"node" : "oTUltX4IQMOUUVeiohTt8A",
"id" : 123,
"type" : "transport",
"action" : "cluster:monitor/tasks/lists",
"start_time_in_millis" :<PHONE_NUMBER>904,
"running_time_in_nanos" : 236042,
"cancellable" : false
}
}
}
}
}
Retrieve information from a particular task
It is also possible to retrieve information for a particular task. The following
example retrieves information about task oTUltX4IQMOUUVeiohTt8A:124
:
GET _tasks/oTUltX4IQMOUUVeiohTt8A:124
If the task isn’t found, the API returns a 404.
To retrieve all children of a particular task:
GET _tasks?parent_task_id=oTUltX4IQMOUUVeiohTt8A:123
If the parent isn’t found, the API does not return a 404.
Get more information about tasks
You can also use the detailed
request parameter to get more information about
the running tasks. This is useful for telling one task from another but is more
costly to execute. For example, fetching all searches using the detailed
request parameter:
GET _tasks?actions=*search&detailed
The API returns the following result:
{
"nodes" : {
"oTUltX4IQMOUUVeiohTt8A" : {
"name" : "H5dfFeA",
"transport_address" : "<IP_ADDRESS>:9300",
"host" : "<IP_ADDRESS>",
"ip" : "<IP_ADDRESS>:9300",
"tasks" : {
"oTUltX4IQMOUUVeiohTt8A:464" : {
"node" : "oTUltX4IQMOUUVeiohTt8A",
"id" : 464,
"type" : "transport",
"action" : "indices:data/read/search",
"description" : "indices[test], types[test], search_type[QUERY_THEN_FETCH], source[{\"query\":...}]",
"start_time_in_millis" :<PHONE_NUMBER>008,
"running_time_in_nanos" : 13991383,
"cancellable" : true
}
}
}
}
}
The new description
field contains human readable text that identifies the
particular request that the task is performing such as identifying the search
request being performed by a search task like the example above. Other kinds of
task have different descriptions, like _reindex
which
has the search and the destination, or _bulk
which just has the
number of requests and the destination indices. Many requests will only have an
empty description because more detailed information about the request is not
easily available or particularly helpful in identifying the request.
Wait for completion
The task API can also be used to wait for completion of a particular task. The
following call will block for 10 seconds or until the task with id
oTUltX4IQMOUUVeiohTt8A:12345
is completed.
GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
You can also wait for all tasks for certain action types to finish. This command
will wait for all reindex
tasks to finish:
GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
Task Cancellation
If a long-running task supports cancellation, it can be cancelled with the cancel
tasks API. The following example cancels task oTUltX4IQMOUUVeiohTt8A:12345
:
POST _tasks/oTUltX4IQMOUUVeiohTt8A:12345/_cancel
The task cancellation command supports the same task selection parameters as the
list tasks command, so multiple tasks can be cancelled at the same time. For
example, the following command will cancel all reindex tasks running on the
nodes nodeId1
and nodeId2
.
wait_for_completion
-
(Optional, Boolean) If
true
, the request blocks until the cancellation of the task and its descendant tasks is completed. Otherwise, the request can return soon after the cancellation is started. Defaults tofalse
.
POST _tasks/_cancel?nodes=nodeId1,nodeId2&actions=*reindex
Task Grouping
The task lists returned by task API commands can be grouped either by nodes
(default) or by parent tasks using the group_by
parameter. The following
command will change the grouping to parent tasks:
GET _tasks?group_by=parents
The grouping can be disabled by specifying none
as a group_by
parameter:
GET _tasks?group_by=none
Identifying running tasks
The X-Opaque-Id
header, when provided on the HTTP request header, is going to
be returned as a header in the response as well as in the headers
field for in
the task information. This allows to track certain calls, or associate certain
tasks with the client that started them:
curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"
The API returns the following result:
HTTP/1.1 200 OK
X-Opaque-Id: 123456 (1)
content-type: application/json; charset=UTF-8
content-length: 831
{
"tasks" : {
"u5lcZHqcQhu-rUoFaqDphA:45" : {
"node" : "u5lcZHqcQhu-rUoFaqDphA",
"id" : 45,
"type" : "transport",
"action" : "cluster:monitor/tasks/lists",
"start_time_in_millis" :<PHONE_NUMBER>749,
"running_time_in_nanos" : 293139,
"cancellable" : false,
"headers" : {
"X-Opaque-Id" : "123456" (2)
},
"children" : [
{
"node" : "u5lcZHqcQhu-rUoFaqDphA",
"id" : 46,
"type" : "direct",
"action" : "cluster:monitor/tasks/lists[n]",
"start_time_in_millis" :<PHONE_NUMBER>750,
"running_time_in_nanos" : 92133,
"cancellable" : false,
"parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45",
"headers" : {
"X-Opaque-Id" : "123456" (3)
}
}
]
}
}
}
-
id as a part of the response header
-
id for the tasks that was initiated by the REST request
-
the child task of the task initiated by the REST request
Voting configuration exclusions API
Adds or removes master-eligible nodes from the voting configuration exclusion list.
Request
POST /_cluster/voting_config_exclusions?node_names=<node_names>
POST /_cluster/voting_config_exclusions?node_ids=<node_ids>
DELETE /_cluster/voting_config_exclusions
Description
By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks.
If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, you must use this API to remove departed nodes from the voting configuration manually. It adds an entry for that node in the voting configuration exclusions list. The cluster then tries to reconfigure the voting configuration to remove that node and to prevent it from returning.
If the API fails, you can safely retry it. Only a successful response guarantees that the node has been removed from the voting configuration and will not be reinstated.
|
Note
|
Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period. They are not required when removing master-ineligible nodes or fewer than half of the master-eligible nodes. |
For more information, see Removing master-eligible nodes.
Query parameters
node_names