Skip to content

[DOCS] Reformats cluster allocation explain API #45603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
szabosteve merged 2 commits into from
Aug 16, 2019
Merged

[DOCS] Reformats cluster allocation explain API #45603

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b41a2b3
[DOCS] Reformats cluster allocation explain API.
szabosteve Aug 15, 2019
ad5e4a8
Update docs/reference/cluster/allocation-explain.asciidoc
szabosteve Aug 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 89 additions & 78 deletions docs/reference/cluster/allocation-explain.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,75 @@
[[cluster-allocation-explain]]
=== Cluster Allocation Explain API

Provides explanations for shard allocations in the cluster.


[[cluster-allocation-explain-api-request]]
==== {api-request-title}

`GET /_cluster/allocation/explain`


[[cluster-allocation-explain-api-desc]]
==== {api-description-title}

The purpose of the cluster allocation explain API is to provide
explanations for shard allocations in the cluster. For unassigned shards,
the explain API provides an explanation for why the shard is unassigned.
For assigned shards, the explain API provides an explanation for why the
shard is remaining on its current node and has not moved or rebalanced to
another node. This API can be very useful when attempting to diagnose why
a shard is unassigned or why a shard continues to remain on its current node
when you might expect otherwise.
another node. This API can be very useful when attempting to diagnose why a
shard is unassigned or why a shard continues to remain on its current node when
you might expect otherwise.

[float]
==== Explain API Request

To explain the allocation of a shard, first an index should exist:
[[cluster-allocation-explain-api-query-params]]
==== {api-query-parms-title}

`include_disk_info`::
(Optional, boolean) If `true`, returns information about disk usage and
shard sizes. Defaults to `false`.

`include_yes_decisions`::
(Optional, boolean) If `true`, returns 'YES' decisions in explanation.
Defaults to `false`.

[source,js]
--------------------------------------------------
PUT /myindex
--------------------------------------------------
// CONSOLE
// TESTSETUP

And then the allocation for shards of that index can be explained:
[[cluster-allocation-explain-api-request-body]]
==== {api-request-body-title}

`current_node`::
(Optional, string) Specifies the node ID or the name of the node to only
explain a shard that is currently located on the specified node.

`index`::
(Optional, string) Specifies the name of the index that you would like an
explanation for.

`primary`::
(Optional, boolean) If `true`, returns explanation for the primary shard
for the given shard ID.

`shard`::
(Optional, integer) Specifies the ID of the shard that you would like an
explanation for.

You can also have {es} explain the allocation of the first unassigned shard that
it finds by sending an empty body for the request.


[[cluster-allocation-explain-api-examples]]
==== {api-examples-title}


//////
[source,js]
--------------------------------------------------
PUT /myindex
--------------------------------------------------
// CONSOLE
// TESTSETUP
//////

[source,js]
--------------------------------------------------
Expand All @@ -35,14 +82,8 @@ GET /_cluster/allocation/explain
--------------------------------------------------
// CONSOLE

Specify the `index` and `shard` id of the shard you would like an explanation
for, as well as the `primary` flag to indicate whether to explain the primary
shard for the given shard id or one of its replica shards. These three request
parameters are required.

You may also specify an optional `current_node` request parameter to only explain
a shard that is currently located on `current_node`. The `current_node` can be
specified as either the node id or node name.
===== Example of the current_node parameter

[source,js]
--------------------------------------------------
Expand All @@ -58,22 +99,8 @@ GET /_cluster/allocation/explain
// TEST[skip:no way of knowing the current_node]
<1> The node where shard 0 currently has a replica on

You can also have Elasticsearch explain the allocation of the first unassigned
shard that it finds by sending an empty body for the request:

[source,js]
--------------------------------------------------
GET /_cluster/allocation/explain
--------------------------------------------------
// CONSOLE

[float]
==== Explain API Response

This section includes examples of the cluster allocation explain API response output
under various scenarios.

//////////////////////////
===== Examples of unassigned primary shard explanations

[source,js]
--------------------------------------------------
Expand All @@ -89,9 +116,8 @@ GET /_cluster/allocation/explain
--------------------------------------------------
// CONSOLE

//////////////////////////

The API response for an unassigned shard:
The API returns the following response for an unassigned primary shard:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -131,36 +157,13 @@ The API response for an unassigned shard:
// TESTRESPONSE[s/"transport_address" : "[^"]*"/"transport_address" : $body.$_path/]
// TESTRESPONSE[s/"node_attributes" : \{\}/"node_attributes" : $body.$_path/]

<1> The current state of the shard
<2> The reason for the shard originally becoming unassigned
<3> Whether to allocate the shard
<4> Whether to allocate the shard to the particular node
<5> The decider which led to the `no` decision for the node
<6> An explanation as to why the decider returned a `no` decision, with a helpful hint pointing to the setting that led to the decision

You can return information gathered by the cluster info service about disk usage
and shard sizes by setting the `include_disk_info` parameter to `true`:

[source,js]
--------------------------------------------------
GET /_cluster/allocation/explain?include_disk_info=true
--------------------------------------------------
// CONSOLE
<1> The current state of the shard.
<2> The reason for the shard originally becoming unassigned.
<3> Whether to allocate the shard.
<4> Whether to allocate the shard to the particular node.
<5> The decider which led to the `no` decision for the node.
<6> An explanation as to why the decider returned a `no` decision, with a helpful hint pointing to the setting that led to the decision.

Additionally, if you would like to include all decisions that were factored into the final
decision, the `include_yes_decisions` parameter will return all decisions for each node:

[source,js]
--------------------------------------------------
GET /_cluster/allocation/explain?include_yes_decisions=true
--------------------------------------------------
// CONSOLE

The default value for `include_yes_decisions` is `false`, which will only
include the `no` decisions in the response. This is generally what you would
want, as the `no` decisions indicate why a shard is unassigned or cannot be moved,
and including all decisions include the `yes` ones adds a lot of verbosity to the
API's response output.

The API response output for an unassigned primary shard that had previously been
allocated to a node in the cluster:
Expand All @@ -184,7 +187,11 @@ allocated to a node in the cluster:
--------------------------------------------------
// NOTCONSOLE

The API response output for a replica that is unassigned due to delayed allocation:

===== Example of an unassigned replica shard explanation

The API response output for a replica that is unassigned due to delayed
allocation:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -233,12 +240,15 @@ The API response output for a replica that is unassigned due to delayed allocati
}
--------------------------------------------------
// NOTCONSOLE
<1> The configured delay before allocating a replica shard that does not exist due to the node holding it leaving the cluster
<2> The remaining delay before allocating the replica shard
<3> Information about the shard data found on a node
<1> The configured delay before allocating a replica shard that does not exist due to the node holding it leaving the cluster.
<2> The remaining delay before allocating the replica shard.
<3> Information about the shard data found on a node.


The API response output for an assigned shard that is not allowed to
remain on its current node and is required to move:
===== Examples of allocated shard explanations

The API response output for an assigned shard that is not allowed to remain on
its current node and is required to move:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -281,9 +291,10 @@ remain on its current node and is required to move:
}
--------------------------------------------------
// NOTCONSOLE
<1> Whether the shard is allowed to remain on its current node
<2> The deciders that factored into the decision of why the shard is not allowed to remain on its current node
<3> Whether the shard is allowed to be allocated to another node
<1> Whether the shard is allowed to remain on its current node.
<2> The deciders that factored into the decision of why the shard is not allowed to remain on its current node.
<3> Whether the shard is allowed to be allocated to another node.


The API response output for an assigned shard that remains on its current node
because moving the shard to another node does not form a better cluster balance:
Expand Down Expand Up @@ -317,6 +328,6 @@ because moving the shard to another node does not form a better cluster balance:
}
--------------------------------------------------
// NOTCONSOLE
<1> Whether rebalancing is allowed on the cluster
<2> Whether the shard can be rebalanced to another node
<3> The reason the shard cannot be rebalanced to the node, in this case indicating that it offers no better balance than the current node
<1> Whether rebalancing is allowed on the cluster.
<2> Whether the shard can be rebalanced to another node.
<3> The reason the shard cannot be rebalanced to the node, in this case indicating that it offers no better balance than the current node.