183 lines
6.3 KiB
Plaintext
183 lines
6.3 KiB
Plaintext
[[cluster-health]]
|
|
=== Cluster health API
|
|
++++
|
|
<titleabbrev>Cluster health</titleabbrev>
|
|
++++
|
|
|
|
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,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/health?wait_for_status=yellow&timeout=50s
|
|
--------------------------------------------------
|
|
|
|
[[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`::
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=cluster-health-status]
|
|
|
|
`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,console]
|
|
--------------------------------------------------
|
|
GET _cluster/health
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT test1\n/]
|
|
|
|
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,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"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
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/testcluster/integTest/]
|
|
// 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 following is an example of getting the cluster health at the
|
|
`shards` level:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/health/twitter?level=shards
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|