Outils et techniques essentiels pour déboguer les problèmes de cluster Elasticsearch

Les problèmes de cluster Elasticsearch se manifestent généralement par un état de santé red ou yellow, des recherches lentes, des écritures rejetées ou des nœuds qui quittent le cluster. La façon la plus rapide de les déboguer est de commencer par la santé du cluster, puis de réduire le problème aux shards, nœuds, règles d'allocation, journaux ou pression sur les ressources.

Ce guide présente les outils intégrés que vous utiliserez le plus souvent : les API _cat, _cluster/allocation/explain, les statistiques de nœuds, les tâches en attente et les journaux Elasticsearch.

Comprendre la santé du cluster Elasticsearch

La santé du cluster vous donne le premier signal :

green : Tous les shards primaires et répliques sont alloués.
yellow : Tous les shards primaires sont alloués, mais un ou plusieurs shards répliques ne le sont pas.
red : Un ou plusieurs shards primaires ne sont pas assignés, donc certaines données sont indisponibles.

Un cluster yellow peut toujours servir les lectures et écritures pour les shards primaires disponibles, mais il a moins de redondance. Un cluster red nécessite une investigation immédiate car les shards primaires affectés sont indisponibles.

Commencez avec les API `_cat`

Les API _cat sont conçues pour des vérifications rapides et lisibles par l'homme.

curl -X GET "localhost:9200/_cat/health?v"
curl -X GET "localhost:9200/_cat/nodes?v&h=name,ip,heap.percent,ram.percent,cpu,disk.used_percent,load_1m,node.role"
curl -X GET "localhost:9200/_cat/shards?v"
curl -X GET "localhost:9200/_cat/indices?v"

Utilisez _cat/health pour confirmer l'état général. Utilisez _cat/shards pour trouver les shards UNASSIGNED, INITIALIZING ou qui se relocalisent fréquemment. Utilisez _cat/nodes pour repérer la pression sur le heap, le CPU ou le disque sur un nœud spécifique.

Pour un cluster red ou yellow, cette commande vous donne une vue ciblée :

curl -X GET "localhost:9200/_cat/shards?v&h=index,shard,prirep,state,unassigned.reason,node&s=state,index"

Expliquer l'allocation des shards

Lorsqu'un shard n'est pas assigné, _cluster/allocation/explain vous indique pourquoi Elasticsearch ne peut pas le placer.

curl -X GET "localhost:9200/_cluster/allocation/explain?pretty" \
  -H 'Content-Type: application/json' -d'
{
  "index": "my_index",
  "shard": 0,
  "primary": true
}'

Vous pouvez également demander à Elasticsearch d'expliquer le premier shard non assigné qu'il trouve :

curl -X GET "localhost:9200/_cluster/allocation/explain?pretty" \
  -H 'Content-Type: application/json' -d'{}'

Lisez les champs can_allocate, allocate_explanation et node_allocation_decisions. Les causes courantes incluent les seuils d'eau du disque, le filtrage d'allocation, les nœuds manquants, les paramètres d'index incompatibles ou un nombre insuffisant de nœuds de données pour le nombre de répliques demandé.

Vérifier les statistiques des nœuds et du cluster

Lorsque la santé est verte mais que les recherches ou écritures sont lentes, vérifiez la pression sur les ressources.

curl -X GET "localhost:9200/_nodes/stats/jvm,fs,os,process,thread_pool?pretty"
curl -X GET "localhost:9200/_cluster/stats?pretty"

Recherchez une utilisation élevée du heap JVM, une pression sur le disque, des tâches de recherche ou d'écriture rejetées et des nœuds avec une charge beaucoup plus élevée que leurs pairs. Un seul nœud surchargé peut ralentir tout le cluster s'il possède des shards chauds.

Pour les rejets de pools de threads, utilisez :

curl -X GET "localhost:9200/_cat/thread_pool/search,write?v&h=node_name,name,active,queue,rejected,completed"

Les tâches rejetées signifient généralement que le nœud n'a pas pu suivre le rythme des requêtes. Corrigez la cause avant d'augmenter les files d'attente : réduisez le coût des requêtes, répartissez les shards, dimensionnez les nœuds ou ralentissez l'indexation en masse.

Examiner les tâches en attente et la récupération

Si les changements d'état du cluster semblent bloqués, vérifiez les tâches en attente :

curl -X GET "localhost:9200/_cluster/pending_tasks?pretty"

Une longue file d'attente peut indiquer une pression sur le nœud maître, des mises à jour fréquentes du mapping, un renouvellement des shards ou des nœuds instables.

Pour le mouvement et la récupération des shards, utilisez :

curl -X GET "localhost:9200/_cat/recovery?v&active_only=true"

Cela vous aide à distinguer un cluster qui se récupère activement d'un cluster bloqué par des règles d'allocation ou des données manquantes.

Lire les journaux Elasticsearch

Les journaux Elasticsearch expliquent souvent ce que les API ne font que suggérer. Vérifiez les journaux sur le nœud affecté, pas seulement sur un nœud aléatoire du cluster.

Recherchez des messages tels que :

master not discovered
flood-stage disk watermark
circuit_breaking_exception
rejected execution
failed to obtain node locks
shard failed

Par exemple, un seuil d'eau de disque de stade d'inondation peut bloquer les écritures en définissant les index affectés en lecture seule jusqu'à ce que la pression sur le disque soit résolue. Après avoir libéré de l'espace disque ou ajouté de la capacité, supprimez le blocage d'écriture uniquement après avoir compris pourquoi le disque s'est rempli :

curl -X PUT "localhost:9200/*/_settings?expand_wildcards=all" \
  -H 'Content-Type: application/json' -d'
{
  "index.blocks.read_only_allow_delete": null
}'

Un flux de débogage pratique

Utilisez cet ordre lorsque vous ne savez pas par où commencer :

Vérifiez _cat/health?v pour voir si le problème est à l'échelle du cluster.
Utilisez _cat/shards?v pour trouver les shards non assignés, en relocalisation ou chauds.
Exécutez _cluster/allocation/explain pour les shards non assignés.
Vérifiez _cat/nodes pour le heap, le CPU, le disque et les rôles des nœuds.
Examinez les journaux des nœuds pour les messages d'allocation, de disque, de JVM et de coupe-circuit.
Utilisez les statistiques des nœuds et des pools de threads si le problème est la latence ou les requêtes rejetées.

Point clé à retenir

Le débogage d'Elasticsearch fonctionne mieux lorsque vous passez de vérifications larges de la santé au shard, nœud ou paramètre exact à l'origine du problème. Commencez par _cat/health, _cat/shards et l'explication d'allocation, puis utilisez les journaux et les statistiques des nœuds pour confirmer la cause racine avant de modifier les paramètres.