140 lines
5.1 KiB
Plaintext
140 lines
5.1 KiB
Plaintext
[[cat-health]]
|
|
=== cat health API
|
|
++++
|
|
<titleabbrev>cat health</titleabbrev>
|
|
++++
|
|
|
|
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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=time]
|
|
|
|
`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::{es-repo-dir}/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:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cat/health?v
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT my-index-000001\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,console]
|
|
--------------------------------------------------
|
|
GET /_cat/health?v&ts=false
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT my-index-000001\n{"settings":{"number_of_replicas": 0}}\n/]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
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%
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/elasticsearch/[^ ]+/ s/0 -/\\d+ (-|\\d+(\\.\\d+)?[ms]+)/ non_json]
|
|
|
|
[[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:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% 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
|
|
[2] 20:20:52 [SUCCESS] es1.vm
|
|
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0
|
|
[3] 20:20:52 [SUCCESS] es2.vm
|
|
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[[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:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% 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
|
|
1384309806 18:30:06 foo green 3 3 1832 916 4 0 0
|
|
^C
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
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. |