From c3a5c3360f7ca6319a33720ce225c829a1ba88c1 Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 14 Mar 2019 09:26:21 +0000 Subject: [PATCH 1/2] Note that GET /_cluster/state is unstable The `GET /_cluster/state` API returns an internal representation of the cluster state that does change from version to version. It's useful for debugging, but it is not intended for regular use by clients. This change adjusts the documentation of `GET /_cluster/state` to clarify that this API yields an internal representation that should not be expected to remain stable between versions. Relates #40061, #40016 --- docs/reference/cluster/state.asciidoc | 66 ++++++++++++++++++--------- 1 file changed, 45 insertions(+), 21 deletions(-) diff --git a/docs/reference/cluster/state.asciidoc b/docs/reference/cluster/state.asciidoc index a20ff04d83f4a..7f49d8703a762 100644 --- a/docs/reference/cluster/state.asciidoc +++ b/docs/reference/cluster/state.asciidoc @@ -1,8 +1,22 @@ [[cluster-state]] == Cluster State -The cluster state API allows to get a comprehensive state information of -the whole cluster. +The cluster state API allows access to metadata representing the state of the +whole cluster. This includes information such as + +* the set of nodes in the cluster + +* all cluster-level settings + +* information about the indices in the cluster, including their mappings and + settings + +* the locations of all the shards in the cluster + +The response is an internal representation of the cluster state and its format +may change from version to version. If possible, you should obtain any +information from the cluster state using the other, more stable, +<>. [source,js] -------------------------------------------------- @@ -10,35 +24,36 @@ GET /_cluster/state -------------------------------------------------- // CONSOLE -The response provides the cluster name, the total compressed size -of the cluster state (its size when serialized for transmission over -the network), and the cluster state itself, which can be filtered to -only retrieve the parts of interest, as described below. +The response provides the cluster state itself, which can be filtered to only +retrieve the parts of interest as described below. -The cluster's `cluster_uuid` is also returned as part of the top-level -response, in addition to the `metadata` section. added[6.4.0] +The cluster's `cluster_uuid` is also returned as part of the top-level response, +in addition to the `metadata` section. added[6.4.0] NOTE: While the cluster is still forming, it is possible for the `cluster_uuid` - to be `_na_` as well as the cluster state's version to be `-1`. + to be `_na_` as well as the cluster state's version to be `-1`. -By default, the cluster state request is routed to the master node, to -ensure that the latest cluster state is returned. -For debugging purposes, you can retrieve the cluster state local to a -particular node by adding `local=true` to the query string. +By default, the cluster state request is routed to the master node, to ensure +that the latest cluster state is returned. For debugging purposes, you can +retrieve the cluster state local to a particular node by adding `local=true` to +the query string. [float] === Response Filters -As the cluster state can grow (depending on the number of shards and indices, your mapping, templates), -it is possible to filter the cluster state response specifying the parts in the URL. +The cluster state contains information about all the indices in the cluster, +including their mappings, as well as templates and other metadata. This means it +can sometimes be quite large. To avoid the need to process all this information +you can request only the part of the cluster state that you need: [source,js] -------------------------------------------------- +GET /_cluster/state/{metrics} GET /_cluster/state/{metrics}/{indices} -------------------------------------------------- // CONSOLE -`metrics` can be a comma-separated list of +`{metrics}` is a comma-separated list of the following options. `version`:: Shows the cluster state version. @@ -50,15 +65,23 @@ GET /_cluster/state/{metrics}/{indices} Shows the `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 indices listed. + 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. `metadata`:: - Shows the `metadata` part of the response. If you supply a comma separated list of indices, the returned output will only contain the indices listed. + 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. `blocks`:: - Shows the `blocks` part of the response + Shows the `blocks` part of the response. + +`_all`:: + Shows all metrics. -The following example returns only `metadata` and `routing_table` data for the `foo` and `bar` indices: +The following example returns only `metadata` and `routing_table` data for the +`foo` and `bar` indices: [source,js] -------------------------------------------------- @@ -74,7 +97,8 @@ GET /_cluster/state/_all/foo,bar -------------------------------------------------- // CONSOLE -And this example return only `blocks` data: +Finally, this example return only the `blocks` metadata: + [source,js] -------------------------------------------------- GET /_cluster/state/blocks From e2b8fad760da2198c1d6ebb301f2a58e3651048e Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 15 Mar 2019 16:21:35 +0000 Subject: [PATCH 2/2] Whitespace --- docs/reference/cluster/state.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/cluster/state.asciidoc b/docs/reference/cluster/state.asciidoc index 7f49d8703a762..34bb69a552c66 100644 --- a/docs/reference/cluster/state.asciidoc +++ b/docs/reference/cluster/state.asciidoc @@ -31,12 +31,12 @@ The cluster's `cluster_uuid` is also returned as part of the top-level response, in addition to the `metadata` section. added[6.4.0] NOTE: While the cluster is still forming, it is possible for the `cluster_uuid` - to be `_na_` as well as the cluster state's version to be `-1`. + to be `_na_` as well as the cluster state's version to be `-1`. By default, the cluster state request is routed to the master node, to ensure -that the latest cluster state is returned. For debugging purposes, you can +that the latest cluster state is returned. For debugging purposes, you can retrieve the cluster state local to a particular node by adding `local=true` to -the query string. +the query string. [float] === Response Filters