From 5d3f90987bdf4002f029e1a83d92f840c74d24c8 Mon Sep 17 00:00:00 2001 From: matthewabbott Date: Thu, 10 Oct 2024 13:55:50 -0700 Subject: [PATCH 1/2] tweaked no-valid-shard-copies message --- .../cluster/allocation-explain.asciidoc | 37 ++++++++++--------- .../routing/allocation/Explanations.java | 2 +- .../elasticsearch/common/ReferenceDocs.java | 1 + .../common/reference-docs-links.txt | 3 +- 4 files changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/reference/cluster/allocation-explain.asciidoc b/docs/reference/cluster/allocation-explain.asciidoc index 7547dd74c5ecd..155c5db29665b 100644 --- a/docs/reference/cluster/allocation-explain.asciidoc +++ b/docs/reference/cluster/allocation-explain.asciidoc @@ -49,32 +49,32 @@ you might expect otherwise. ==== {api-query-parms-title} `include_disk_info`:: - (Optional, Boolean) If `true`, returns information about disk usage and - shard sizes. Defaults to `false`. +(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`. +(Optional, Boolean) If `true`, returns 'YES' decisions in explanation. +Defaults to `false`. [[cluster-allocation-explain-api-request-body]] ==== {api-request-body-title} `current_node`:: - (Optional, string) Specifies the node ID or the name of the node currently - holding the shard to explain. To explain an unassigned shard, omit this - parameter. +(Optional, string) Specifies the node ID or the name of the node currently +holding the shard to explain. To explain an unassigned shard, omit this +parameter. `index`:: - (Optional, string) Specifies the name of the index that you would like an - explanation for. +(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. +(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. +(Optional, integer) Specifies the ID of the shard that you would like an +explanation for. [[cluster-allocation-explain-api-examples]] ==== {api-examples-title} @@ -162,7 +162,7 @@ node. ====== Maximum number of retries exceeded The following response contains an allocation explanation for an unassigned -primary shard that has reached the maximum number of allocation retry attempts. +primary shard that has reached the maximum number of allocation retry attempts. [source,js] ---- @@ -204,9 +204,10 @@ primary shard that has reached the maximum number of allocation retry attempts. ---- // NOTCONSOLE -If decider message indicates a transient allocation issue, use -<> to retry allocation. +If decider message indicates a transient allocation issue, use +the <> API to retry allocation. +[[no-valid-shard-copy]] ====== No valid shard copy The following response contains an allocation explanation for an unassigned @@ -334,7 +335,7 @@ queued to allocate but currently waiting on other queued shards. ---- // NOTCONSOLE -This is a transient message that might appear when a large amount of shards are allocating. +This is a transient message that might appear when a large amount of shards are allocating. ===== Assigned shard @@ -437,7 +438,7 @@ cluster balance. ===== No arguments If you call the API with no arguments, {es} retrieves an allocation explanation -for an arbitrary unassigned primary or replica shard, returning any unassigned primary shards first. +for an arbitrary unassigned primary or replica shard, returning any unassigned primary shards first. [source,console] ---- diff --git a/server/src/main/java/org/elasticsearch/cluster/routing/allocation/Explanations.java b/server/src/main/java/org/elasticsearch/cluster/routing/allocation/Explanations.java index 337c4bbd2a27b..80503a27ae1a6 100644 --- a/server/src/main/java/org/elasticsearch/cluster/routing/allocation/Explanations.java +++ b/server/src/main/java/org/elasticsearch/cluster/routing/allocation/Explanations.java @@ -32,7 +32,7 @@ public static final class Allocation { public static final String NO_COPIES = """ Elasticsearch can't allocate this shard because there are no copies of its data in the cluster. Elasticsearch will allocate \ this shard when a node holding a good copy of its data joins the cluster. If no such node is available, restore this index \ - from a recent snapshot."""; + from a recent snapshot. For more information, see\s""" + org.elasticsearch.common.ReferenceDocs.ALLOCATION_EXPLAIN_NO_COPIES; public static final String DELAYED_WITH_ALTERNATIVE = """ The node containing this shard copy recently left the cluster. Elasticsearch is waiting for it to return. If the node does not \ diff --git a/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java b/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java index b059113b4098c..ae8de474daf93 100644 --- a/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java +++ b/server/src/main/java/org/elasticsearch/common/ReferenceDocs.java @@ -81,6 +81,7 @@ public enum ReferenceDocs { X_OPAQUE_ID, FORMING_SINGLE_NODE_CLUSTERS, CIRCUIT_BREAKER_ERRORS, + ALLOCATION_EXPLAIN_NO_COPIES, // this comment keeps the ';' on the next line so every entry above has a trailing ',' which makes the diff for adding new links cleaner ; diff --git a/server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt b/server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt index ab9a6b253be7a..b2a4c7992d1fe 100644 --- a/server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt +++ b/server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt @@ -42,4 +42,5 @@ MAX_SHARDS_PER_NODE size-your-shards FLOOD_STAGE_WATERMARK fix-watermark-errors.html X_OPAQUE_ID api-conventions.html#x-opaque-id FORMING_SINGLE_NODE_CLUSTERS modules-discovery-bootstrap-cluster.html#modules-discovery-bootstrap-cluster-joining -CIRCUIT_BREAKER_ERRORS circuit-breaker-errors.html \ No newline at end of file +CIRCUIT_BREAKER_ERRORS circuit-breaker-errors.html +ALLOCATION_EXPLAIN_NO_COPIES cluster-allocation-explain.html#no-valid-shard-copy From 950e1d74339775a1f135ae7737c64dfb08c029b0 Mon Sep 17 00:00:00 2001 From: matthewabbott Date: Thu, 10 Oct 2024 14:01:42 -0700 Subject: [PATCH 2/2] untweaked misformatting in allocation explain asciidoc --- .../cluster/allocation-explain.asciidoc | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/reference/cluster/allocation-explain.asciidoc b/docs/reference/cluster/allocation-explain.asciidoc index 155c5db29665b..6aa0c6110277c 100644 --- a/docs/reference/cluster/allocation-explain.asciidoc +++ b/docs/reference/cluster/allocation-explain.asciidoc @@ -49,32 +49,32 @@ you might expect otherwise. ==== {api-query-parms-title} `include_disk_info`:: -(Optional, Boolean) If `true`, returns information about disk usage and -shard sizes. Defaults to `false`. + (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`. + (Optional, Boolean) If `true`, returns 'YES' decisions in explanation. + Defaults to `false`. [[cluster-allocation-explain-api-request-body]] ==== {api-request-body-title} `current_node`:: -(Optional, string) Specifies the node ID or the name of the node currently -holding the shard to explain. To explain an unassigned shard, omit this -parameter. + (Optional, string) Specifies the node ID or the name of the node currently + holding the shard to explain. To explain an unassigned shard, omit this + parameter. `index`:: -(Optional, string) Specifies the name of the index that you would like an -explanation for. + (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. + (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. + (Optional, integer) Specifies the ID of the shard that you would like an + explanation for. [[cluster-allocation-explain-api-examples]] ==== {api-examples-title}