Dépannage : Vérification et interprétation de l'état de santé d'un cluster Elasticsearch

L'état de santé d'un cluster Elasticsearch est l'un de ces contrôles qui semblent simples jusqu'à ce que l'alarme se déclenche. L'API vous donne une couleur, mais la couleur n'est que le point de départ. Un cluster vert peut encore être lent. Un cluster jaune peut être parfaitement utilisable pendant une courte fenêtre de maintenance. Un cluster rouge peut signifier qu'un petit index de test est indisponible, ou que la recherche orientée client manque de données réelles.

Lorsque je vérifie l'état de santé d'un cluster Elasticsearch, j'essaie de ne pas passer directement du rouge à des commandes de récupération dangereuses. Je veux d'abord répondre à trois questions : les shards primaires sont-ils attribués, les réplicas sont-ils attribués, et le cluster essaie-t-il actuellement de se rétablir tout seul ? Les commandes ci-dessous sont celles que j'utilise pour passer d'une couleur de santé générale à une raison spécifique.

Commencez par l'API de santé

Pour une vue rapide en terminal, _cat/health est suffisant :

curl -s "http://localhost:9200/_cat/health?v"

Une réponse typique ressemble à ceci :

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

Les champs que je regarde en premier sont status, node.total, node.data, relo, init, unassign et pending_tasks. Un statut jaune avec init ou relo supérieur à zéro peut simplement être un cluster qui récupère après un redémarrage. Un statut jaune avec des shards non attribués et aucun mouvement nécessite généralement une enquête.

Pour l'automatisation, utilisez l'API JSON au lieu d'analyser la sortie _cat :

curl -s "http://localhost:9200/_cluster/health?pretty"

Cette réponse inclut des champs tels que active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards et delayed_unassigned_shards. Ces noms sont plus faciles à utiliser dans les scripts et les contrôles de surveillance.

Ce que signifient vraiment le vert, le jaune et le rouge

Le vert signifie que chaque shard primaire et chaque shard réplica configuré sont attribués. Cela ne signifie pas que les requêtes sont rapides, que le disque est sain ou que les mappings sont bien conçus. Cela signifie seulement qu'Elasticsearch a placé les shards qu'il était censé placer.

Le jaune signifie que tous les shards primaires sont attribués, mais qu'au moins un shard réplica n'est pas attribué. Vos données devraient toujours être consultables car les primaires sont disponibles. Le risque est la redondance. Si le nœud hébergeant un primaire tombe en panne alors que son réplica n'est toujours pas attribué, cet index peut devenir rouge.

Le rouge signifie qu'au moins un shard primaire n'est pas attribué. Les recherches sur les index affectés peuvent échouer ou renvoyer des résultats partiels, et les écritures sur ces shards ne peuvent pas se dérouler normalement. Le rouge mérite une attention immédiate, mais l'action correcte dépend de la raison pour laquelle le primaire n'est pas attribué.

Un exemple courant de petit cluster est un cluster de développement à nœud unique avec un réplica configuré. Il restera jaune car Elasticsearch ne placera pas un réplica sur le même nœud que son primaire. Ce n'est pas un mystère et ce n'est pas une raison pour forcer l'allocation. Ajoutez soit un autre nœud de données, soit définissez les réplicas à zéro pour cet index :

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

N'utilisez pas ce paramètre à la légère en production. Il supprime la redondance pour cet index.

Trouvez les shards non attribués exacts

Après la couleur de santé, listez les shards :

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

Recherchez UNASSIGNED. La colonne prirep vous indique si le shard est un primaire (p) ou un réplica (r). Cette distinction est plus importante que la couleur elle-même. Quelques réplicas non attribués signifient généralement une tolérance aux pannes réduite. Un primaire non attribué signifie qu'au moins une partie d'un index est indisponible.

Si vous voyez de nombreux shards non attribués après un redémarrage planifié d'un nœud, vérifiez également l'allocation différée :

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

Elasticsearch peut attendre avant de réallouer des réplicas après le départ d'un nœud, car le nœud peut revenir rapidement. Ce comportement évite les changements inutiles de réseau et de disque lors des redémarrages progressifs.

Demandez à Elasticsearch pourquoi l'allocation a échoué

L'API d'explication d'allocation est la meilleure étape suivante. Vous pouvez demander pour n'importe quel shard non attribué :

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

Ou demander pour un shard spécifique :

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

Lisez unassigned_info, can_allocate et node_allocation_decisions. La partie utile est généralement en langage clair : seuil de disque dépassé, allocation désactivée, aucun attribut de nœud correspondant, trop de shards sur un nœud, ou un réplica ne peut pas être placé car un seul nœud existe.

Si l'explication indique allocation_delayed, attendez seulement si le nœud manquant devrait revenir bientôt. Si l'explication indique qu'aucun nœud ne satisfait les règles d'allocation, attendre ne résoudra pas le problème.

Guide pour un cluster jaune

Pour un état de santé jaune, j'utilise cet ordre :

1. Vérifiez si le cluster a suffisamment de nœuds de données pour le nombre de réplicas configuré.
2. Vérifiez les seuils de disque avec _cat/allocation.
3. Vérifiez si l'allocation a été désactivée pendant la maintenance.
4. Vérifiez les filtres de routage au niveau de l'index et les règles de connaissance de la topologie.
5. Décidez s'il faut ajouter de la capacité, réduire le nombre de réplicas ou corriger une mauvaise règle.

La vérification du nombre de nœuds est simple. Si un index a number_of_replicas: 2, Elasticsearch a besoin de trois nœuds de données appropriés pour placer un primaire plus deux réplicas. « Approprié » est important. Si la connaissance de la topologie nécessite des zones séparées, vous avez besoin de nœuds dans ces zones, pas seulement de trois nœuds quelconques.

Vérifiez l'allocation et le disque :

curl -s "http://localhost:9200/_cat/allocation?v"

Si les nœuds sont au-dessus des seuils de disque, Elasticsearch peut refuser de nouvelles allocations de shards. Libérez de l'espace, ajoutez des nœuds, étendez les disques ou supprimez les anciens index après avoir pris des snapshots. Augmenter les seuils peut faire gagner du temps dans une urgence contrôlée, mais cela ne crée pas de capacité.

Vérifiez les paramètres d'allocation :

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

Si cluster.routing.allocation.enable est none, l'allocation est désactivée. C'est courant après des scripts de maintenance qui ont oublié de la réactiver. Réactivez-la avec :

curl -X PUT "http://localhost:9200/_cluster/settings?pretty"   -H 'Content-Type: application/json'   -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

Vérifiez également si la valeur a été définie comme transient ; les paramètres persistants et transitoires peuvent tous deux affecter le comportement.

Guide pour un cluster rouge

Pour un état de santé rouge, ralentissez et identifiez le rayon d'impact. Ne commencez pas par allocate_empty_primary. Cette commande accepte la perte de données par conception.

Trouvez d'abord les shards primaires affectés :

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

Inspectez ensuite l'un d'eux avec l'explication d'allocation :

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

Si le primaire n'est pas attribué parce qu'un nœud est hors service, votre meilleure récupération peut être de restaurer ce nœud. Vérifiez le service, le disque, les logs JVM et le chemin réseau. Si une copie réplica existe sur un autre nœud, Elasticsearch devrait normalement la promouvoir. Si ce n'est pas le cas, la sortie d'explication et les logs vous disent généralement pourquoi.

Si les données sont perdues ou corrompues, restaurez à partir d'un snapshot. C'est le chemin de récupération propre. Si aucun snapshot n'existe et que les données peuvent être reconstruites à partir d'une autre source, vous pouvez décider d'allouer un primaire vide :

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

Utilisez-le uniquement lorsque la perte du contenu du shard est acceptable. Le nom est littéral : Elasticsearch alloue un primaire vide et passe à autre chose.

Surveillez la récupération au lieu de deviner

Après une correction, surveillez le mouvement des shards :

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

La récupération peut être limitée par la vitesse du disque, la bande passante réseau, la taille des shards et les paramètres de récupération du cluster. Un gros shard peut rester dans l'état INITIALIZING plus longtemps que prévu. C'est différent d'être bloqué. Si les compteurs d'octets et de fichiers progressent dans _cat/recovery, laissez faire.

Vérifiez également les tâches en attente du cluster lorsque l'état de santé ne change pas :

curl -s "http://localhost:9200/_cat/pending_tasks?v"

Une longue file d'attente peut indiquer un nœud maître surchargé ou des décisions d'allocation répétées qui ne peuvent pas aboutir.

Un exemple pratique

Supposons que _cat/health affiche jaune avec deux shards non attribués. _cat/shards montre que les deux sont des réplicas pour logs-2026.05.24. L'explication d'allocation indique que le cluster ne peut pas allouer car chaque nœud de données est au-dessus du seuil de disque bas. La solution n'est pas de réacheminer manuellement les shards. La solution est la capacité : supprimez les anciens index après les avoir snapshotés, ajoutez du stockage, ajoutez des nœuds de données ou déplacez les données froides ailleurs.

Autre exemple : un cluster de trois nœuds est jaune après un redémarrage progressif. _cluster/health montre delayed_unassigned_shards: 8. Le nœud arrêté est déjà en train de revenir. Dans ce cas, attendre quelques minutes peut être correct. Forcer l'allocation immédiatement peut créer un travail de récupération supplémentaire et ralentir le redémarrage.

Troisième exemple : un cluster de laboratoire à nœud unique est jaune en permanence. _cat/shards montre que chaque shard non attribué est un réplica. L'index a un réplica. Elasticsearch se comporte correctement. Définissez les réplicas à zéro pour le laboratoire ou ajoutez un deuxième nœud de données.

Gardez la vérification de santé honnête

L'état de santé du cluster devrait faire partie de la surveillance, mais les règles d'alerte ont besoin de contexte. Alertez immédiatement sur le rouge. Alertez sur le jaune lorsqu'il dure au-delà d'une courte fenêtre de maintenance, lorsque les réplicas non attribués augmentent, ou lorsque la raison est la pression sur le disque. Suivez les seuils de disque, le nombre de nœuds, la pression JVM et le succès des snapshots en parallèle de la couleur de santé. La couleur vous indique par où commencer ; les API de shard et d'allocation vous disent quoi faire ensuite.

Quand les vérifications de santé ne correspondent pas aux symptômes des utilisateurs

Parfois, le cluster est vert et les utilisateurs se plaignent encore. Ce n'est pas une contradiction. L'état de santé du cluster concerne l'attribution des shards, pas la latence ou l'exactitude des requêtes. Si la santé est verte mais que les recherches sont lentes, passez à la latence de recherche, aux pools de threads, aux shards chauds, à la pression JVM et à la latence de stockage. Un cluster vert avec un nœud de données surchargé peut toujours sembler cassé.

L'inverse se produit également. Un cluster peut être jaune pour une raison inoffensive, comme un environnement de développement à nœud unique avec des réplicas configurés. L'habitude utile est de relier l'état de santé à l'impact commercial. Quel index est affecté ? Est-ce un primaire ou un réplica ? L'application lit-elle à partir de cet index en ce moment ? Est-ce pendant une maintenance planifiée ? Ces questions vous évitent de traiter chaque statut jaune comme une catastrophe.

Pour les systèmes orientés client, j'aime garder une petite table de procédures en dehors d'Elasticsearch : modèle d'index, service propriétaire, source de données, politique de snapshot, si les données peuvent être rejouées, et qui approuve une récupération destructive. Lors d'un incident rouge, cette table est souvent plus utile qu'un autre tableau de bord. Si clickstream-* peut être rejoué depuis Kafka, le choix de récupération est différent d'un index qui contient des documents générés par les utilisateurs sans copie en amont.

Habitudes de commande plus sûres

Utilisez des noms d'index explicites lorsque vous le pouvez. Les wildcards sont pratiques, mais ils cachent le rayon d'impact. Avant d'exécuter une commande qui modifie les paramètres ou supprime des données, listez ce que le modèle correspond :

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

Conservez la sortie des commandes de l'incident. Collez les résultats de l'explication d'allocation, les listes de shards et les réponses de santé dans le ticket. L'état d'Elasticsearch change rapidement pendant la récupération, et vous pourriez avoir besoin de la sortie précédente pour comprendre pourquoi une décision a été prise.

Si la sécurité est activée, exécutez ces commandes avec un utilisateur ayant les privilèges minimum utiles pour le diagnostic et un processus séparé plus restreint pour les opérations destructives. Dans un incident stressant, il est trop facile de coller une commande d'écriture dans le même shell où vous inspectiez seulement la santé.

Que vérifier après le retour du cluster au vert

Le vert n'est pas la fin de l'incident. Vérifiez si les réplicas ont été reconstruits sur les nœuds attendus, si le disque est toujours proche des seuils, et si un index a été laissé avec des paramètres temporaires tels que number_of_replicas: 0, un refresh_interval long, ou une allocation désactivée.

Confirmez également que les snapshots réussissent après la récupération. Un cluster qui vient d'avoir des problèmes de shard peut avoir exposé une lacune dans la rétention, les identifiants du référentiel ou la planification des snapshots. Si la récupération dépendait de la chance car aucun snapshot n'existait, notez-le et corrigez-le avant la prochaine panne.

Enfin, révisez les alertes. Si les humains ont remarqué le problème avant la surveillance, ajoutez ou ajustez les alertes pour la santé rouge, la santé jaune de longue durée, la pression sur les seuils de disque, les nœuds manquants, les snapshots échoués et les élections de maître répétées. Une couleur de santé de cluster est utile, mais la meilleure alerte vous indique pourquoi la couleur a changé et quel index est affecté.