mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-18 10:54:54 +00:00
[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]]
|
||||||
=== Cluster Health
|
=== Cluster Health
|
||||||
|
|
||||||
The cluster health API allows to get a very simple status on the health
|
Returns the health status of a cluster.
|
||||||
of the cluster. For example, on a quiet single node cluster with a single index
|
|
||||||
with one shard and one replica, this:
|
[[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]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
@ -12,7 +144,8 @@ GET _cluster/health
|
|||||||
// CONSOLE
|
// CONSOLE
|
||||||
// TEST[s/^/PUT test1\n/]
|
// 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]
|
[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/"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/]
|
// 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
|
The following is an example of getting the cluster health at the
|
||||||
`shards` level:
|
`shards` level:
|
||||||
|
|
||||||
|
|||||||
@ -1,6 +1,16 @@
|
|||||||
[[cluster-state]]
|
[[cluster-state]]
|
||||||
=== 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
|
The cluster state API allows access to metadata representing the state of the
|
||||||
whole cluster. This includes information such as
|
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
|
* information about the indices in the cluster, including their mappings and
|
||||||
settings
|
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
|
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
|
may change from version to version. If possible, you should obtain any
|
||||||
information from the cluster state using the other, more stable,
|
information from the cluster state using the other, more stable,
|
||||||
<<cluster,cluster APIs>>.
|
<<cluster,cluster APIs>>.
|
||||||
|
|
||||||
[source,js]
|
|
||||||
--------------------------------------------------
|
|
||||||
GET /_cluster/state
|
|
||||||
--------------------------------------------------
|
|
||||||
// CONSOLE
|
|
||||||
|
|
||||||
The response provides the cluster state itself, which can be filtered to only
|
The response provides the cluster state itself, which can be filtered to only
|
||||||
retrieve the parts of interest as described below.
|
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
|
retrieve the cluster state local to a particular node by adding `local=true` to
|
||||||
the query string.
|
the query string.
|
||||||
|
|
||||||
[float]
|
[[cluster-state-api-path-params]]
|
||||||
==== Response Filters
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
The cluster state contains information about all the indices in the cluster,
|
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
|
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
|
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:
|
you can request only the part of the cluster state that you need:
|
||||||
|
|
||||||
[source,js]
|
`{metrics}`::
|
||||||
--------------------------------------------------
|
(Optional, string) A comma-separated list of the following options:
|
||||||
GET /_cluster/state/{metrics}
|
+
|
||||||
GET /_cluster/state/{metrics}/{indices}
|
--
|
||||||
--------------------------------------------------
|
`_all`::
|
||||||
// CONSOLE
|
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`::
|
`nodes`::
|
||||||
Shows the cluster state version.
|
Shows the `nodes` part of the response.
|
||||||
|
|
||||||
`master_node`::
|
`routing_nodes`::
|
||||||
Shows the elected `master_node` part of the response
|
Shows the `routing_nodes` part of the response.
|
||||||
|
|
||||||
`nodes`::
|
`routing_table`::
|
||||||
Shows the `nodes` part of the response
|
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`::
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
||||||
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.
|
|
||||||
|
|
||||||
`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`::
|
[[cluster-state-api-query-params]]
|
||||||
Shows the `blocks` part of the response.
|
==== {api-query-parms-title}
|
||||||
|
|
||||||
`_all`::
|
`allow_no_indices`::
|
||||||
Shows all metrics.
|
(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
|
The following example returns only `metadata` and `routing_table` data for the
|
||||||
`foo` and `bar` indices:
|
`foo` and `bar` indices:
|
||||||
@ -97,7 +138,7 @@ GET /_cluster/state/_all/foo,bar
|
|||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
|
|
||||||
Finally, this example return only the `blocks` metadata:
|
This example returns only the `blocks` metadata:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user