mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-28 07:59:10 +00:00
24163d10b7
With #29331 we added support for the cluster health API to the high-level REST client. The transport client does not support the level parameter, and it always returns all the info needed for shards level rendering. We have maintained that behaviour when adding support for cluster health to the high-level REST client, to ease migration, but the correct thing to do is to default the high-level REST client to `cluster` level, which is the same default as when going through the Elasticsearch REST layer.
206 lines
9.0 KiB
Plaintext
206 lines
9.0 KiB
Plaintext
[[java-rest-high-cluster-health]]
|
|
=== Cluster Health API
|
|
|
|
The Cluster Health API allows getting cluster health.
|
|
|
|
[[java-rest-high-cluster-health-request]]
|
|
==== Cluster Health Request
|
|
|
|
A `ClusterHealthRequest`:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request]
|
|
--------------------------------------------------
|
|
There are no required parameters. By default, the client will check all indices and will not wait
|
|
for any events.
|
|
|
|
==== Indices
|
|
|
|
Indices which should be checked can be passed in the constructor:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-ctr]
|
|
--------------------------------------------------
|
|
|
|
Or using the corresponding setter method:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-setter]
|
|
--------------------------------------------------
|
|
|
|
==== Other parameters
|
|
|
|
Other parameters can be passed only through setter methods:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-timeout]
|
|
--------------------------------------------------
|
|
<1> Timeout for the request as a `TimeValue`. Defaults to 30 seconds
|
|
<2> As a `String`
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-master-timeout]
|
|
--------------------------------------------------
|
|
<1> Timeout to connect to the master node as a `TimeValue`. Defaults to the same as `timeout`
|
|
<2> As a `String`
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-status]
|
|
--------------------------------------------------
|
|
<1> The status to wait (e.g. `green`, `yellow`, or `red`). Accepts a `ClusterHealthStatus` value.
|
|
<2> Using predefined method
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-events]
|
|
--------------------------------------------------
|
|
<1> The priority of the events to wait for. Accepts a `Priority` value.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-level]
|
|
--------------------------------------------------
|
|
<1> The level of detail of the returned health information. Accepts a `ClusterHealthRequest.Level` value.
|
|
Default value is `cluster`.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-relocation]
|
|
--------------------------------------------------
|
|
<1> Wait for 0 relocating shards. Defaults to `false`
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-initializing]
|
|
--------------------------------------------------
|
|
<1> Wait for 0 initializing shards. Defaults to `false`
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-nodes]
|
|
--------------------------------------------------
|
|
<1> Wait for `N` nodes in the cluster. Defaults to `0`
|
|
<2> Using `>=N`, `<=N`, `>N` and `<N` notation
|
|
<3> Using `ge(N)`, `le(N)`, `gt(N)`, `lt(N)` notation
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-active]
|
|
--------------------------------------------------
|
|
|
|
<1> Wait for all shards to be active in the cluster
|
|
<2> Wait for `N` shards to be active in the cluster
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-local]
|
|
--------------------------------------------------
|
|
<1> Non-master node can be used for this request. Defaults to `false`
|
|
|
|
[[java-rest-high-cluster-health-sync]]
|
|
==== Synchronous Execution
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute]
|
|
--------------------------------------------------
|
|
|
|
[[java-rest-high-cluster-health-async]]
|
|
==== Asynchronous Execution
|
|
|
|
The asynchronous execution of a cluster health request requires both the
|
|
`ClusterHealthRequest` instance and an `ActionListener` instance to be
|
|
passed to the asynchronous method:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-async]
|
|
--------------------------------------------------
|
|
<1> The `ClusterHealthRequest` to execute and the `ActionListener` to use
|
|
when the execution completes
|
|
|
|
The asynchronous method does not block and returns immediately. Once it is
|
|
completed the `ActionListener` is called back using the `onResponse` method
|
|
if the execution successfully completed or using the `onFailure` method if
|
|
it failed.
|
|
|
|
A typical listener for `ClusterHealthResponse` looks like:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-listener]
|
|
--------------------------------------------------
|
|
<1> Called when the execution is successfully completed. The response is
|
|
provided as an argument
|
|
<2> Called in case of a failure. The raised exception is provided as an argument
|
|
|
|
[[java-rest-high-cluster-health-response]]
|
|
==== Cluster Health Response
|
|
|
|
The returned `ClusterHealthResponse` contains the next information about the
|
|
cluster:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-general]
|
|
--------------------------------------------------
|
|
<1> Name of the cluster
|
|
<2> Cluster status (`green`, `yellow` or `red`)
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-request-status]
|
|
--------------------------------------------------
|
|
<1> Whether request was timed out while processing
|
|
<2> Status of the request (`OK` or `REQUEST_TIMEOUT`). Other errors will be thrown as exceptions
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-nodes]
|
|
--------------------------------------------------
|
|
<1> Number of nodes in the cluster
|
|
<2> Number of data nodes in the cluster
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shards]
|
|
--------------------------------------------------
|
|
<1> Number of active shards
|
|
<2> Number of primary active shards
|
|
<3> Number of relocating shards
|
|
<4> Number of initializing shards
|
|
<5> Number of unassigned shards
|
|
<6> Number of unassigned shards that are currently being delayed
|
|
<7> Percent of active shards
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-task]
|
|
--------------------------------------------------
|
|
<1> Maximum wait time of all tasks in the queue
|
|
<2> Number of currently pending tasks
|
|
<3> Number of async fetches that are currently ongoing
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-indices]
|
|
--------------------------------------------------
|
|
<1> Detailed information about indices in the cluster
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-index]
|
|
--------------------------------------------------
|
|
<1> Detailed information about a specific index
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shard-details]
|
|
--------------------------------------------------
|
|
<1> Detailed information about a specific shard |