Clean up ES troubleshooting titles (#319)

* Fix some titles * Another batch * Another batch * Another batch * Make nav titles consistent * Testing fix for build errors * Revert "Testing fix for build errors" This reverts commit 57c9c2b.
elastic · Feb 10, 2025 · 4c7a0f6 · 4c7a0f6
1 parent 8116b17
commit 4c7a0f6
Show file tree

Hide file tree

Showing 42 changed files with 102 additions and 36 deletions.
diff --git a/troubleshoot/elasticsearch/add-repository.md b/troubleshoot/elasticsearch/add-repository.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Broken repositories
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/add-repository.html
 ---
 
-# Troubleshooting broken repositories [add-repository]
+# Troubleshoot broken repositories [add-repository]
 
 There are several situations where the [Health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/health-api.html) might report an issue regarding the integrity of snapshot repositories in the cluster. The following pages explain the recommended actions for diagnosing corrupted, unknown, and invalid repositories:
 

diff --git a/troubleshoot/elasticsearch/add-tier.md b/troubleshoot/elasticsearch/add-tier.md
@@ -1,9 +1,14 @@
 ---
+navigation_title: Index allocation data tier
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/add-tier.html
 ---
 
-# Add a missing tier to the system [add-tier]
+% marciw move this page to a new index allocation subsection
+% or just move it down in the ToC
+% and this page really really needs rewriting
+
+# Add a preferred data tier to a deployment [add-tier]
 
 The allocation of indices in an {{es}} deployment can be allocated on [data tiers](../../manage-data/lifecycle/data-tiers.md).
 

diff --git a/troubleshoot/elasticsearch/allow-all-cluster-allocation.md b/troubleshoot/elasticsearch/allow-all-cluster-allocation.md
@@ -1,5 +1,6 @@
 ---
-mapped_pages:
+navigation_title: Data allocation
+mapped_pages: 
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/allow-all-cluster-allocation.html
 ---
 

diff --git a/troubleshoot/elasticsearch/allow-all-index-allocation.md b/troubleshoot/elasticsearch/allow-all-index-allocation.md
@@ -1,8 +1,12 @@
 ---
+navigation_title: Index allocation
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/allow-all-index-allocation.html
 ---
 
+% Need to retitle to be about the problem, not the solution
+% New subsection about unassigned shards?
+
 # Allow Elasticsearch to allocate the index [allow-all-index-allocation]
 
 The allocation of data can be controlled using the [enable allocation configuration](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-routing-allocation-enable-setting). In certain circumstances users might want to temporarily disable or restrict the allocation of data.

diff --git a/troubleshoot/elasticsearch/corruption-troubleshooting.md b/troubleshoot/elasticsearch/corruption-troubleshooting.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Data corruption
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/corruption-troubleshooting.html
 ---
 
-# Troubleshooting corruption [corruption-troubleshooting]
+# Troubleshoot data corruption [corruption-troubleshooting]
 
 {{es}} expects that the data it reads from disk is exactly the data it previously wrote. If it detects that the data on disk is different from what it wrote then it will report some kind of exception such as:
 

diff --git a/troubleshoot/elasticsearch/decrease-disk-usage-data-node.md b/troubleshoot/elasticsearch/decrease-disk-usage-data-node.md
@@ -1,4 +1,5 @@
 ---
+navigation_title: Decrease disk usage
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/decrease-disk-usage-data-node.html
 ---

diff --git a/troubleshoot/elasticsearch/diagnose-unassigned-shards.md b/troubleshoot/elasticsearch/diagnose-unassigned-shards.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Unassigned shards
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/diagnose-unassigned-shards.html
 ---
 
+% marciw move to a new Unassigned shards subsection
+
 # Diagnose unassigned shards [diagnose-unassigned-shards]
 
 There are multiple reasons why shards might get unassigned, ranging from misconfigured allocation settings to lack of disk space.

diff --git a/troubleshoot/elasticsearch/diagnosing-corrupted-repositories.md b/troubleshoot/elasticsearch/diagnosing-corrupted-repositories.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Corrupted repositories
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/diagnosing-corrupted-repositories.html
 ---
 
-# Diagnosing corrupted repositories [diagnosing-corrupted-repositories]
+# Diagnose corrupted repositories [diagnosing-corrupted-repositories]
 
 Multiple {{es}} deployments are writing to the same snapshot repository. {{es}} doesn’t support this configuration and only one cluster is allowed to write to the same repository. See [Repository contents](../../deploy-manage/tools/snapshot-and-restore.md#snapshot-repository-contents) for potential side-effects of corruption of the repository contents, which may not be resolved by the following guide. To remedy the situation mark the repository as read-only or remove it from all the other deployments, and re-add (recreate) the repository in the current deployment:
 

diff --git a/troubleshoot/elasticsearch/diagnosing-invalid-repositories.md b/troubleshoot/elasticsearch/diagnosing-invalid-repositories.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Invalid repositories
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/diagnosing-invalid-repositories.html
 ---
 
-# Diagnosing invalid repositories [diagnosing-invalid-repositories]
+# Diagnose invalid repositories [diagnosing-invalid-repositories]
 
 When an {{es}} node faces an unexpected exception when trying to instantiate a snapshot repository, it will mark the repository as "invalid" and write a warning to the log file. Use the following steps to diagnose the underlying cause of this issue:
 

diff --git a/troubleshoot/elasticsearch/diagnosing-unknown-repositories.md b/troubleshoot/elasticsearch/diagnosing-unknown-repositories.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Unknown repositories
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/diagnosing-unknown-repositories.html
 ---
 
-# Diagnosing unknown repositories [diagnosing-unknown-repositories]
+# Diagnose unknown repositories [diagnosing-unknown-repositories]
 
 When a snapshot repository is marked as "unknown", it means that an {{es}} node is unable to instantiate the repository due to an unknown repository type. This is usually caused by a missing plugin on the node. Make sure each node in the cluster has the required plugins by following the following steps:
 

diff --git a/troubleshoot/elasticsearch/diagnostic.md b/troubleshoot/elasticsearch/diagnostic.md
@@ -1,11 +1,9 @@
 ---
-navigation_title: "Capture diagnostics"
+navigation_title: Diagnostics
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/diagnostic.html
 ---
 
-
-
 # Capture diagnostics [diagnostic]
 
 

diff --git a/troubleshoot/elasticsearch/discovery-troubleshooting.md b/troubleshoot/elasticsearch/discovery-troubleshooting.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Discovery
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/discovery-troubleshooting.html
 ---
 
-# Troubleshooting discovery [discovery-troubleshooting]
+# Troubleshoot discovery [discovery-troubleshooting]
 
 In most cases, the discovery and election process completes quickly, and the master node remains elected for a long period of time.
 

diff --git a/troubleshoot/elasticsearch/elasticsearch-client-java-api-client/java.md b/troubleshoot/elasticsearch/elasticsearch-client-java-api-client/java.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Java
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/troubleshooting.html
 ---
 
-# Java [troubleshooting]
+# Troubleshoot {{es}} Java client [troubleshooting]
 
 
 ## Exceptions [_exceptions] 

diff --git a/troubleshoot/elasticsearch/elasticsearch-client-javascript-api/nodejs.md b/troubleshoot/elasticsearch/elasticsearch-client-javascript-api/nodejs.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Node.js
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/timeout-best-practices.html
 ---
 
-# Node.js [timeout-best-practices]
+# Troubleshoot {{es}} Node.js client [timeout-best-practices]
 
 Starting in 9.0.0, this client is configured to not time out any HTTP request by default. {{es}} will always eventually respond to any request, even if it takes several minutes. Reissuing a request that it has not responded to yet can cause performance side effects. See the [official {{es}} recommendations for HTTP clients](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html#_http_client_configuration) for more information.
 

diff --git a/troubleshoot/elasticsearch/elasticsearch-client-net-api/net.md b/troubleshoot/elasticsearch/elasticsearch-client-net-api/net.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: .NET
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/troubleshooting.html
 ---
 
-# .NET [troubleshooting]
+# Troubleshoot {{es}} .NET client [troubleshooting]
 
 The client can provide rich details about what occurred in the request pipeline during the process of making a request, as well as be configured to provide the raw request and response JSON
 

diff --git a/troubleshoot/elasticsearch/elasticsearch-client-ruby-api/ruby.md b/troubleshoot/elasticsearch/elasticsearch-client-ruby-api/ruby.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Ruby
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/troubleshooting.html
 ---
 
-# Ruby [troubleshooting]
+# Troubleshoot {{es}} Ruby client [troubleshooting]
 
 Use the information in this section to troubleshoot common problems and find answers for frequently asked questions.
 

diff --git a/troubleshoot/elasticsearch/elasticsearch-hadoop/elasticsearch-for-apache-hadoop.md b/troubleshoot/elasticsearch/elasticsearch-hadoop/elasticsearch-for-apache-hadoop.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Apache Hadoop
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/hadoop/current/troubleshooting.html
 ---
 
-# Elasticsearch for Apache Hadoop [troubleshooting]
+# Troubleshoot Elasticsearch for Apache Hadoop [troubleshooting]
 
 Unfortunately, sometimes things do not go as expected and your elasticsearch-hadoop job execution might go awry: incorrect data might be read or written, the job might take significantly longer than expected or you might face some exception. This section tries to provide help and tips for doing your own diagnostics, identifying the problem and hopefully fixing it.
 

diff --git a/...hoot/elasticsearch/elasticsearch-reference/index-lifecycle-management-errors.md b/...hoot/elasticsearch/elasticsearch-reference/index-lifecycle-management-errors.md
@@ -1,9 +1,12 @@
 ---
+navgiation_title: Index lifecycle management errors
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-error-handling.html
 ---
 
-# Index lifecycle management errors [index-lifecycle-error-handling]
+% marciw move so this is with other ILM topics
+
+# Fix index lifecycle management errors [index-lifecycle-error-handling]
 
 When [{{ilm-init}}](../../../manage-data/lifecycle/index-lifecycle-management.md) executes a lifecycle policy, it’s possible for errors to occur while performing the necessary index operations for a step. When this happens, {{ilm-init}} moves the index to an `ERROR` step. If {{ilm-init}} cannot resolve the error automatically, execution is halted until you resolve the underlying issues with the policy, index, or cluster.
 

diff --git a/troubleshoot/elasticsearch/elasticsearch-reference/remote-clusters.md b/troubleshoot/elasticsearch/elasticsearch-reference/remote-clusters.md
@@ -1,12 +1,12 @@
 ---
-navigation_title: "Troubleshooting"
+navigation_title: Remote clusters
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-troubleshooting.html
 ---
 
 
 
-# Remote clusters [remote-clusters-troubleshooting]
+# Troubleshoot remote clusters [remote-clusters-troubleshooting]
 
 
 You may encounter several issues when setting up a remote cluster for {{ccr}} or {{ccs}}.

diff --git a/troubleshoot/elasticsearch/elasticsearch-reference/security.md b/troubleshoot/elasticsearch/elasticsearch-reference/security.md
@@ -1,13 +1,12 @@
 ---
-navigation_title: "Troubleshooting"
+navigation_title: Security
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-troubleshooting.html
 ---
 
+% marciw: this page needs to move to the security folder
 
-
-# Security [security-troubleshooting]
-
+# Troubleshoot {{es}} security [security-troubleshooting]
 
 Use the information in this section to troubleshoot common problems and find answers for frequently asked questions.
 

diff --git a/troubleshoot/elasticsearch/fix-common-cluster-issues.md b/troubleshoot/elasticsearch/fix-common-cluster-issues.md
@@ -1,4 +1,5 @@
 ---
+navigation_title: Common cluster issues
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-common-cluster-issues.html
 ---

diff --git a/troubleshoot/elasticsearch/fix-data-node-out-of-disk.md b/troubleshoot/elasticsearch/fix-data-node-out-of-disk.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Data nodes out of disk
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-data-node-out-of-disk.html
 ---
 
+% marciw move to new "out of disk" subsection
+
 # Fix data nodes out of disk [fix-data-node-out-of-disk]
 
 {{es}} is using data nodes to distribute your data inside the cluster. If one or more of these nodes are running out of space, {{es}} takes action to redistribute your data within the nodes so all nodes have enough available disk space. If {{es}} cannot facilitate enough available space in a node, then you will need to intervene in one of two ways:

diff --git a/troubleshoot/elasticsearch/fix-master-node-out-of-disk.md b/troubleshoot/elasticsearch/fix-master-node-out-of-disk.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Master nodes out of disk
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-master-node-out-of-disk.html
 ---
 
+% marciw move to new "out of disk" subsection
+
 # Fix master nodes out of disk [fix-master-node-out-of-disk]
 
 {{es}} is using master nodes to coordinate the cluster. If the master or any master eligible nodes are running out of space, you need to ensure that they have enough disk space to function. If the [health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/health-api.html) reports that your master node is out of space you need to increase the disk capacity of your master nodes.

diff --git a/troubleshoot/elasticsearch/fix-other-node-out-of-disk.md b/troubleshoot/elasticsearch/fix-other-node-out-of-disk.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Other nodes out of disk
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-other-node-out-of-disk.html
 ---
 
+% marciw move to new "out of disk" subsection
+
 # Fix other role nodes out of disk [fix-other-node-out-of-disk]
 
 {{es}} can use dedicated nodes to execute other functions apart from storing data or coordinating the cluster, for example machine learning. If one or more of these nodes are running out of space, you need to ensure that they have enough disk space to function. If the [health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/health-api.html) reports that a node that is not a master and does not contain data is out of space you need to increase the disk capacity of this node.

diff --git a/troubleshoot/elasticsearch/high-cpu-usage.md b/troubleshoot/elasticsearch/high-cpu-usage.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: High CPU usage
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/high-cpu-usage.html
 ---
 
-# High CPU usage [high-cpu-usage]
+# Symptom: High CPU usage [high-cpu-usage]
 
 {{es}} uses [thread pools](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-threadpool.html) to manage CPU resources for concurrent operations. High CPU usage typically means one or more thread pools are running low.
 

diff --git a/troubleshoot/elasticsearch/increase-capacity-data-node.md b/troubleshoot/elasticsearch/increase-capacity-data-node.md
@@ -1,4 +1,5 @@
 ---
+navigation_title: Increase disk capacity
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/increase-capacity-data-node.html
 ---

diff --git a/troubleshoot/elasticsearch/increase-cluster-shard-limit.md b/troubleshoot/elasticsearch/increase-cluster-shard-limit.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Total number of shards per node reached
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/increase-cluster-shard-limit.html
 ---
 
+% marciw move to a new Unassigned shards subsection
+
 # Total number of shards per node has been reached [increase-cluster-shard-limit]
 
 Elasticsearch tries to take advantage of all the available resources by distributing data (index shards) amongst the cluster nodes.

diff --git a/troubleshoot/elasticsearch/increase-shard-limit.md b/troubleshoot/elasticsearch/increase-shard-limit.md
@@ -1,8 +1,11 @@
 ---
+navigation_title: Total number of shards for an index exceeded
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/increase-shard-limit.html
 ---
 
+% marciw retitle; move to a new Unassigned shards subsection
+
 # Total number of shards for an index on a single node exceeded [increase-shard-limit]
 
 Elasticsearch tries to take advantage of all the available resources by distributing data (index shards) among nodes in the cluster.

diff --git a/troubleshoot/elasticsearch/increase-tier-capacity.md b/troubleshoot/elasticsearch/increase-tier-capacity.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Not enough nodes to allocate shard replicas
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/increase-tier-capacity.html
 ---
 
-# Not enough nodes to allocate all shard replicas [increase-tier-capacity]
+# Warning: Not enough nodes to allocate all shard replicas [increase-tier-capacity]
 
 Distributing copies of the data (index shard replicas) on different nodes can parallelize processing requests thus speeding up search queries. This can be achieved by increasing the number of replica shards up to the maximum value (total number of nodes minus one) which also serves the purpose to protect against hardware failure. If the index has a preferred tier, Elasticsearch will only place the copies of the data for that index on nodes in the target tier.
 

diff --git a/troubleshoot/elasticsearch/monitoring-troubleshooting.md b/troubleshoot/elasticsearch/monitoring-troubleshooting.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Monitoring
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/monitoring-troubleshooting.html
 ---
 
-# Troubleshooting monitoring [monitoring-troubleshooting]
+# Troubleshoot monitoring [monitoring-troubleshooting]
 
 Use the information in this section to troubleshoot common problems and find answers for frequently asked questions. See also [Troubleshooting monitoring in {{ls}}](https://www.elastic.co/guide/en/logstash/current/monitoring-troubleshooting.html).
 

diff --git a/troubleshoot/elasticsearch/red-yellow-cluster-status.md b/troubleshoot/elasticsearch/red-yellow-cluster-status.md
@@ -1,4 +1,5 @@
 ---
+navigation_title: Red or yellow health status
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/red-yellow-cluster-status.html
 ---

diff --git a/troubleshoot/elasticsearch/repeated-snapshot-failures.md b/troubleshoot/elasticsearch/repeated-snapshot-failures.md
@@ -1,9 +1,10 @@
 ---
+navigation_title: Snapshot policy failures
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/repeated-snapshot-failures.html
 ---
 
-# Addressing repeated snapshot policy failures [repeated-snapshot-failures]
+# Fix repeated snapshot policy failures [repeated-snapshot-failures]
 
 Repeated snapshot failures are usually an indicator of a problem with your deployment. Continuous failures of automated snapshots can leave a deployment without recovery options in cases of data loss or outages.
 

diff --git a/troubleshoot/elasticsearch/start-ilm.md b/troubleshoot/elasticsearch/start-ilm.md
@@ -1,10 +1,14 @@
 ---
+navigation_title: Index lifecycle management
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/start-ilm.html
 ---
 
 # Start index lifecycle management [start-ilm]
 
+% marciw consider moving out of troubleshooting and into how-tos
+% marciw or add troubleshooting info from elsewhere
+
 Automatic index lifecycle and data retention management is currently disabled.
 
 In order to start the automatic {{ilm}} service, follow these steps: