[DOCS] Reformats cluster health and cluster state APIs (#45206)
Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
fb959d188c
commit
9f62c04637
|
|
@ -1,9 +1,141 @@
|
|||
[[cluster-health]]
|
||||
=== Cluster Health
|
||||
|
||||
The cluster health API allows to get a very simple status on the health
|
||||
of the cluster. For example, on a quiet single node cluster with a single index
|
||||
with one shard and one replica, this:
|
||||
Returns the health status of a cluster.
|
||||
|
||||
[[cluster-health-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET _cluster/health/{index}`
|
||||
|
||||
[[cluster-health-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The cluster health API returns a simple status on the health of the
|
||||
cluster. The API can also be executed against one or more indices to get just
|
||||
the specified indices health.
|
||||
|
||||
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):
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_cluster/health?wait_for_status=yellow&timeout=50s
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[[cluster-health-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
||||
|
||||
[[cluster-health-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
`level`::
|
||||
(Optional, string) Can be one of `cluster`, `indices` or `shards`. Controls
|
||||
the details level of the health information returned. Defaults to `cluster`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
`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, or `0` to not
|
||||
wait. Defaults to `0`.
|
||||
|
||||
`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 use `ge(N)`, `le(N)`, `gt(N)` and
|
||||
`lt(N)` notation.
|
||||
|
||||
`wait_for_status`::
|
||||
(Optional, string) One of `green`, `yellow` or `red`. 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.
|
||||
|
||||
[[cluster-health-api-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
`cluster_name`::
|
||||
(string) The name of the cluster.
|
||||
|
||||
`status`::
|
||||
(string) The health status of the cluster.
|
||||
|
||||
`timed_out`::
|
||||
(boolean) If `false` the response returned within the period of
|
||||
time that is specified by the `timeout` 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.
|
||||
|
||||
[[cluster-health-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -12,7 +144,8 @@ GET _cluster/health
|
|||
// CONSOLE
|
||||
// TEST[s/^/PUT test1\n/]
|
||||
|
||||
Returns this:
|
||||
The API returns the following response in case of a quiet single node cluster
|
||||
with a single index with one shard and one replica:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -38,90 +171,6 @@ Returns this:
|
|||
// TESTRESPONSE[s/"number_of_pending_tasks" : 0,/"number_of_pending_tasks" : $body.number_of_pending_tasks,/]
|
||||
// TESTRESPONSE[s/"task_max_waiting_in_queue_millis": 0/"task_max_waiting_in_queue_millis": $body.task_max_waiting_in_queue_millis/]
|
||||
|
||||
|
||||
The API can also be executed against one or more indices to get just the
|
||||
specified indices health:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_cluster/health/test1,test2
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[s/^/PUT test1\nPUT test2\n/]
|
||||
|
||||
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):
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_cluster/health?wait_for_status=yellow&timeout=50s
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[float]
|
||||
[[request-params]]
|
||||
==== Request Parameters
|
||||
|
||||
The cluster health API accepts the following request parameters:
|
||||
|
||||
`level`::
|
||||
Can be one of `cluster`, `indices` or `shards`. Controls the
|
||||
details level of the health information returned. Defaults to `cluster`.
|
||||
|
||||
`wait_for_status`::
|
||||
One of `green`, `yellow` or `red`. 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.
|
||||
|
||||
`wait_for_no_relocating_shards`::
|
||||
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_no_initializing_shards`::
|
||||
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_active_shards`::
|
||||
A number controlling to how many active shards to wait for, `all` to wait
|
||||
for all shards in the cluster to be active, or `0` to not wait. Defaults to `0`.
|
||||
|
||||
`wait_for_nodes`::
|
||||
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 use `ge(N)`, `le(N)`, `gt(N)` and
|
||||
`lt(N)` notation.
|
||||
|
||||
`wait_for_events`::
|
||||
Can be one of `immediate`, `urgent`, `high`, `normal`, `low`, `languid`.
|
||||
Wait until all currently queued events with the given priority are processed.
|
||||
|
||||
`timeout`::
|
||||
A time based parameter controlling how long to wait if one of
|
||||
the wait_for_XXX are provided. Defaults to `30s`.
|
||||
|
||||
`master_timeout`::
|
||||
A time based parameter controlling how long to wait if the master has not been
|
||||
discovered yet or disconnected.
|
||||
If not provided, uses the same value as `timeout`.
|
||||
|
||||
`local`::
|
||||
If `true` returns the local node information and does not provide
|
||||
the state from master node. Default: `false`.
|
||||
|
||||
|
||||
The following is an example of getting the cluster health at the
|
||||
`shards` level:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,16 @@
|
|||
[[cluster-state]]
|
||||
=== Cluster State
|
||||
|
||||
Returns metadata about the state of the cluster.
|
||||
|
||||
[[cluster-state-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_cluster/state/{metrics}/{index}`
|
||||
|
||||
[[cluster-state-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The cluster state API allows access to metadata representing the state of the
|
||||
whole cluster. This includes information such as
|
||||
|
||||
|
|
@ -11,19 +21,13 @@ whole cluster. This includes information such as
|
|||
* information about the indices in the cluster, including their mappings and
|
||||
settings
|
||||
|
||||
* the locations of all the shards in the cluster
|
||||
* the locations of all the shards in the cluster.
|
||||
|
||||
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,cluster APIs>>.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_cluster/state
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
The response provides the cluster state itself, which can be filtered to only
|
||||
retrieve the parts of interest as described below.
|
||||
|
||||
|
|
@ -38,47 +42,84 @@ 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.
|
||||
|
||||
[float]
|
||||
==== Response Filters
|
||||
[[cluster-state-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
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:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_cluster/state/{metrics}
|
||||
GET /_cluster/state/{metrics}/{indices}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
`{metrics}`::
|
||||
(Optional, string) A comma-separated list of the following options:
|
||||
+
|
||||
--
|
||||
`_all`::
|
||||
Shows all metrics.
|
||||
|
||||
`blocks`::
|
||||
Shows the `blocks` part of the response.
|
||||
|
||||
`{metrics}` is a comma-separated list of the following options.
|
||||
`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.
|
||||
|
||||
`version`::
|
||||
Shows the cluster state version.
|
||||
`nodes`::
|
||||
Shows the `nodes` part of the response.
|
||||
|
||||
`master_node`::
|
||||
Shows the elected `master_node` part of the response
|
||||
`routing_nodes`::
|
||||
Shows the `routing_nodes` part of the response.
|
||||
|
||||
`nodes`::
|
||||
Shows the `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.
|
||||
--
|
||||
|
||||
`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.
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
||||
|
||||
`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.
|
||||
|
||||
`blocks`::
|
||||
Shows the `blocks` part of the response.
|
||||
[[cluster-state-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
`_all`::
|
||||
Shows all metrics.
|
||||
`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).
|
||||
|
||||
`expand_wildcards`::
|
||||
(Optional, string) Whether to expand wildcard expression to concrete indices
|
||||
that are open, closed or both. Available options: `open`, `closed`, `none`,
|
||||
`all`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
||||
|
||||
`ignore_unavailable`::
|
||||
(Optional, boolean) If `true`, unavailable indices (missing or closed) will
|
||||
be ignored.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
||||
|
||||
`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, time units>>) Specifies the maximum time to wait
|
||||
for wait_for_metadata_version before timing out.
|
||||
|
||||
|
||||
[[cluster-state-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example returns only `metadata` and `routing_table` data for the
|
||||
`foo` and `bar` indices:
|
||||
|
|
@ -97,7 +138,7 @@ GET /_cluster/state/_all/foo,bar
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
Finally, this example return only the `blocks` metadata:
|
||||
This example returns only the `blocks` metadata:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue