mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
dc26886ee1
The `GET _cluster/state` API is really only suitable for debugging or diagnostics. Its response format is not documented since it changes fairly freely between versions. Today we mention in its docs that this API is unstable, and deliberately omit a description of its response format, but we don't explicitly say that it's only for diagnostics and is unsuitable for consumption by external tools that might try and use it for monitoring. This commit adjusts the docs to give some more explicit guidance about how it should and shouldn't be used.
160 lines
5.3 KiB
Text
160 lines
5.3 KiB
Text
[[cluster-state]]
|
|
=== Cluster state API
|
|
++++
|
|
<titleabbrev>Cluster state</titleabbrev>
|
|
++++
|
|
|
|
Returns an internal representation of the cluster state for debugging or
|
|
diagnostic purposes.
|
|
|
|
[[cluster-state-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_cluster/state/<metrics>/<target>`
|
|
|
|
[[cluster-state-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `monitor` or
|
|
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[cluster-state-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
The _cluster state_ is an internal data structure which keeps track of a
|
|
variety of information needed by every node, including:
|
|
|
|
* The identity and attributes of the other nodes in the cluster
|
|
|
|
* Cluster-wide settings
|
|
|
|
* Index metadata, including the mapping and settings for each index
|
|
|
|
* The location and status of every shard copy in the cluster
|
|
|
|
The elected master node ensures that every node in the cluster has a copy of
|
|
the same cluster state. The cluster state API lets you retrieve a
|
|
representation of this internal state for debugging or diagnostic purposes. You
|
|
may need to consult the {es} source code to determine the precise meaning of
|
|
the response.
|
|
|
|
By default the cluster state API will route requests to the elected master node
|
|
since this node is the authoritative source of cluster states. You can also
|
|
retrieve the cluster state held on the node handling the API request by adding
|
|
the query parameter `?local=true`.
|
|
|
|
{es} may need to expend significant effort to compute a response to this API in
|
|
larger clusters, and the response may comprise a very large quantity of data.
|
|
If you use this API repeatedly, your cluster may become unstable.
|
|
|
|
[[cluster-state-api-unstable-warning]]
|
|
WARNING: The response is a representation of an internal data structure. Its
|
|
format is not subject to the same compatibility guarantees as other more stable
|
|
APIs and may change from version to version. **Do not query this API using
|
|
external monitoring tools.** Instead, obtain the information you require using
|
|
other more stable <<cluster,cluster APIs>>.
|
|
|
|
[[cluster-state-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
The cluster state can sometimes be very large, and {es} may consume significant
|
|
resources while computing a response to this API. To reduce the size of the
|
|
response, you can request only the part of the cluster state in which you are
|
|
interested:
|
|
|
|
`<metrics>`::
|
|
(Optional, string) A comma-separated list of the following options:
|
|
+
|
|
--
|
|
`_all`::
|
|
Shows all metrics.
|
|
|
|
`blocks`::
|
|
Shows the `blocks` part of the response.
|
|
|
|
`master_node`::
|
|
Shows the `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.
|
|
|
|
`nodes`::
|
|
Shows the `nodes` part of the response.
|
|
|
|
`routing_nodes`::
|
|
Shows the `routing_nodes` part of the response.
|
|
|
|
`routing_table`::
|
|
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.
|
|
--
|
|
|
|
`<target>`::
|
|
(Optional, string) Comma-separated list of data streams, indices, and aliases
|
|
used to limit the request. Supports wildcards (`*`). To target all data streams
|
|
and indices, omit this parameter or use `*` or `_all`.
|
|
|
|
[[cluster-state-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`allow_no_indices`::
|
|
(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).
|
|
+
|
|
Defaults to `true`.
|
|
|
|
`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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
|
|
|
`ignore_unavailable`::
|
|
(Optional, Boolean) If `true`, unavailable indices (missing or closed) will
|
|
be ignored.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
|
|
|
|
include::{es-repo-dir}/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
|
|
`foo` and `bar` data streams or indices:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/metadata,routing_table/foo,bar
|
|
--------------------------------------------------
|
|
|
|
The next example returns all available metadata for `foo` and `bar`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/_all/foo,bar
|
|
--------------------------------------------------
|
|
|
|
This example returns only the `blocks` metadata:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/blocks
|
|
--------------------------------------------------
|