OpenSearch/docs/reference/cat/health.asciidoc

141 lines
5.1 KiB
Plaintext
Raw Normal View History

2013-11-14 20:14:39 -05:00
[[cat-health]]
=== cat health
2013-11-14 20:14:39 -05:00
Returns the health status of a cluster, similar to the <<cluster-health,cluster
health>> API.
[[cat-health-api-request]]
==== {api-request-title}
`GET /_cat/health`
[[cat-health-api-desc]]
==== {api-description-title}
You can use the cat health API to get the health status of a cluster.
[[timestamp]]
This API is often used to check malfunctioning clusters. To help you
track cluster health alongside log files and alerting systems, the API returns
timestamps in two formats:
* `HH:MM:SS`, which is human-readable but includes no date information.
* https://en.wikipedia.org/wiki/Unix_time[Unix `epoch` time], which is
machine-sortable and includes date information. This is useful for cluster
recoveries that take multiple days.
You can use the cat health API to verify cluster health across multiple nodes.
See <<cat-health-api-example-across-nodes>>.
You also can use the API to track the recovery of a large cluster
over a longer period of time. See <<cat-health-api-example-large-cluster>>.
[[cat-health-api-query-params]]
==== {api-query-parms-title}
include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
`ts` (timestamps)::
(Optional, boolean) If `true`, returns `HH:MM:SS` and
https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. Defaults to
`true`.
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
[[cat-health-api-example]]
==== {api-examples-title}
[[cat-health-api-example-timestamp]]
===== Example with a timestamp
By default, the cat health API returns `HH:MM:SS` and
https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. For example:
2013-11-14 20:14:39 -05:00
[source,js]
--------------------------------------------------
GET /_cat/health?v
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n{"settings":{"number_of_replicas": 0}}\n/]
The API returns the following response:
[source,txt]
--------------------------------------------------
epoch timestamp cluster status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1475871424 16:17:04 elasticsearch green 1 1 1 1 0 0 0 0 - 100.0%
--------------------------------------------------
// TESTRESPONSE[s/1475871424 16:17:04/\\d+ \\d+:\\d+:\\d+/]
// TESTRESPONSE[s/elasticsearch/[^ ]+/ s/0 -/\\d+ (-|\\d+(\\.\\d+)?[ms]+)/ non_json]
[[cat-health-api-example-no-timestamp]]
===== Example without a timestamp
You can use the `ts` (timestamps) parameter to disable timestamps. For example:
[source,js]
--------------------------------------------------
GET /_cat/health?v&ts=false
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n{"settings":{"number_of_replicas": 0}}\n/]
The API returns the following response:
[source,txt]
2013-11-14 20:14:39 -05:00
--------------------------------------------------
cluster status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
elasticsearch green 1 1 1 1 0 0 0 0 - 100.0%
2013-11-14 20:14:39 -05:00
--------------------------------------------------
// TESTRESPONSE[s/elasticsearch/[^ ]+/ s/0 -/\\d+ (-|\\d+(\\.\\d+)?[ms]+)/ non_json]
2013-11-14 20:14:39 -05:00
[[cat-health-api-example-across-nodes]]
===== Example across nodes
You can use the cat health API to verify the health of a cluster across nodes.
For example:
2013-11-14 20:14:39 -05:00
[source,sh]
2013-11-14 20:14:39 -05:00
--------------------------------------------------
% pssh -i -h list.of.cluster.hosts curl -s localhost:9200/_cat/health
[1] 20:20:52 [SUCCESS] es3.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0
2013-11-14 20:14:39 -05:00
[2] 20:20:52 [SUCCESS] es1.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0
2013-11-14 20:14:39 -05:00
[3] 20:20:52 [SUCCESS] es2.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0
2013-11-14 20:14:39 -05:00
--------------------------------------------------
// NOTCONSOLE
2013-11-14 20:14:39 -05:00
[[cat-health-api-example-large-cluster]]
===== Example with a large cluster
You can use the cat health API to track the recovery of a large cluster over a
longer period of time. You can do this by including the cat health API request
in a delayed loop. For example:
2013-11-14 20:14:39 -05:00
[source,sh]
2013-11-14 20:14:39 -05:00
--------------------------------------------------
% while true; do curl localhost:9200/_cat/health; sleep 120; done
1384309446 18:24:06 foo red 3 3 20 20 0 0 1812 0
1384309566 18:26:06 foo yellow 3 3 950 916 0 12 870 0
1384309686 18:28:06 foo yellow 3 3 1328 916 0 12 492 0
2013-11-14 20:14:39 -05:00
1384309806 18:30:06 foo green 3 3 1832 916 4 0 0
^C
--------------------------------------------------
// NOTCONSOLE
2013-11-14 20:14:39 -05:00
In this example, the recovery took roughly six minutes, from `18:24:06` to
`18:30:06`. If this recovery took hours, you could continue to monitor the
number of `UNASSIGNED` shards, which should drop. If the number of `UNASSIGNED`
shards remains static, it would indicate an issue with the cluster recovery.