Fehlerbehebung: Überprüfung und Interpretation des Elasticsearch-Cluster-Health-Status

Der Elasticsearch-Cluster-Health ist eine dieser Überprüfungen, die einfach erscheinen, bis der Alarm losgeht. Die API liefert eine Farbe, aber die Farbe ist nur der Ausgangspunkt. Ein grüner Cluster kann trotzdem langsam sein. Ein gelber Cluster kann für ein kurzes Wartungsfenster vollkommen nutzbar sein. Ein roter Cluster kann bedeuten, dass ein kleiner Testindex nicht verfügbar ist, oder dass die kundenorientierte Suche echte Daten vermissen lässt.

Wenn ich den Elasticsearch-Cluster-Health überprüfe, versuche ich, nicht direkt von rot zu gefährlichen Wiederherstellungsbefehlen zu springen. Ich möchte zuerst drei Fragen beantworten: Sind Primär-Shards zugewiesen, sind Replikate zugewiesen, und versucht der Cluster derzeit, sich selbst zu erholen? Die folgenden Befehle verwende ich, um von einer allgemeinen Health-Farbe zu einem spezifischen Grund zu gelangen.

Beginnen Sie mit der Health-API

Für eine schnelle Terminal-Ansicht ist _cat/health ausreichend:

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

Eine typische Antwort sieht so aus:

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

Die Felder, die ich zuerst betrachte, sind status, node.total, node.data, relo, init, unassign und pending_tasks. Ein gelber Status mit init oder relo größer als Null kann einfach ein Cluster sein, der sich nach einem Neustart erholt. Ein gelber Status mit nicht zugewiesenen Shards und keiner Bewegung erfordert normalerweise eine Untersuchung.

Für die Automatisierung verwenden Sie die JSON-API anstatt die _cat-Ausgabe zu parsen:

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

Diese Antwort enthält Felder wie active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards und delayed_unassigned_shards. Diese Namen sind in Skripten und Monitoring-Prüfungen einfacher zu verwenden.

Was grün, gelb und rot wirklich bedeuten

Grün bedeutet, dass jeder Primär-Shard und jedes konfigurierte Replikat-Shard zugewiesen ist. Es bedeutet nicht, dass Abfragen schnell sind, die Festplatte gesund ist oder die Mappings gut entworfen sind. Es bedeutet nur, dass Elasticsearch die Shards platziert hat, die es platzieren soll.

Gelb bedeutet, dass alle Primär-Shards zugewiesen sind, aber mindestens ein Replikat-Shard nicht zugewiesen ist. Ihre Daten sollten weiterhin durchsuchbar sein, da die Primär-Shards verfügbar sind. Das Risiko ist die Redundanz. Wenn der Knoten, der einen Primär-Shard hält, ausfällt, während sein Replikat noch nicht zugewiesen ist, kann dieser Index rot werden.

Rot bedeutet, dass mindestens ein Primär-Shard nicht zugewiesen ist. Suchen gegen betroffene Indizes können fehlschlagen oder partielle Ergebnisse liefern, und Schreibvorgänge auf diese Shards können nicht normal fortgesetzt werden. Rot verdient sofortige Aufmerksamkeit, aber die richtige Aktion hängt davon ab, warum der Primär-Shard nicht zugewiesen ist.

Ein häufiges Beispiel für kleine Cluster ist ein Einzelknoten-Entwicklungscluster mit einem konfigurierten Replikat. Es bleibt gelb, weil Elasticsearch kein Replikat auf denselben Knoten wie seinen Primär-Shard setzen wird. Das ist kein Rätsel und kein Grund, die Zuweisung zu erzwingen. Fügen Sie entweder einen weiteren Datenknoten hinzu oder setzen Sie die Replikate für diesen Index auf Null:

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

Verwenden Sie diese Einstellung nicht leichtfertig in der Produktion. Sie entfernt die Redundanz für diesen Index.

Finden Sie die genauen nicht zugewiesenen Shards

Nach der Health-Farbe listen Sie die Shards auf:

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

Suchen Sie nach UNASSIGNED. Die Spalte prirep sagt Ihnen, ob der Shard ein Primär-Shard (p) oder ein Replikat (r) ist. Diese Unterscheidung ist wichtiger als die Farbe selbst. Ein paar nicht zugewiesene Replikate bedeuten normalerweise eine reduzierte Ausfallsicherheit. Ein nicht zugewiesener Primär-Shard bedeutet, dass mindestens ein Teil eines Index nicht verfügbar ist.

Wenn Sie nach einem geplanten Knotenneustart viele nicht zugewiesene Shards sehen, überprüfen Sie auch die verzögerte Zuweisung:

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

Elasticsearch wartet möglicherweise, bevor es Replikate neu zuweist, nachdem ein Knoten den Cluster verlassen hat, da der Knoten möglicherweise schnell zurückkommt. Dieses Verhalten vermeidet unnötigen Netzwerk- und Festplattenverschleiß während rollierender Neustarts.

Fragen Sie Elasticsearch, warum die Zuweisung fehlgeschlagen ist

Die Allocation-Explain-API ist der beste nächste Schritt. Sie können nach jedem nicht zugewiesenen Shard fragen:

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

Oder nach einem bestimmten Shard fragen:

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
  }'

Lesen Sie unassigned_info, can_allocate und node_allocation_decisions. Der nützliche Teil ist normalerweise in einfachem Englisch: Festplatten-Watermark überschritten, Zuweisung deaktiviert, kein passendes Knotenattribut, zu viele Shards auf einem Knoten oder ein Replikat kann nicht platziert werden, weil nur ein Knoten existiert.

Wenn die Erklärung allocation_delayed besagt, warten Sie nur, wenn erwartet wird, dass der fehlende Knoten bald zurückkommt. Wenn die Erklärung besagt, dass kein Knoten die Zuweisungsregeln erfüllt, wird Warten das Problem nicht beheben.

Gelber Cluster-Playbook

Bei gelbem Health verwende ich diese Reihenfolge:

Überprüfen, ob der Cluster genügend Datenknoten für die konfigurierte Replikatanzahl hat.
Festplatten-Watermarks mit _cat/allocation überprüfen.
Überprüfen, ob die Zuweisung während der Wartung deaktiviert wurde.
Indexebene-Routing-Filter und Awareness-Regeln überprüfen.
Entscheiden, ob Kapazität hinzugefügt, die Replikatanzahl gesenkt oder eine fehlerhafte Regel behoben werden soll.

Die Knotenanzahl-Prüfung ist einfach. Wenn ein Index number_of_replicas: 2 hat, benötigt Elasticsearch drei geeignete Datenknoten, um einen Primär-Shard plus zwei Replikate zu platzieren. „Geeignet“ ist wichtig. Wenn Allocation Awareness separate Zonen erfordert, benötigen Sie Knoten in diesen Zonen, nicht nur irgendwelche drei Knoten.

Überprüfen Sie Zuweisung und Festplatte:

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

Wenn Knoten über den Festplatten-Watermarks liegen, verweigert Elasticsearch möglicherweise neue Shard-Zuweisungen. Geben Sie Speicherplatz frei, fügen Sie Knoten hinzu, erweitern Sie Festplatten oder löschen Sie alte Indizes nach der Erstellung von Snapshots. Das Erhöhen der Watermarks kann in einem kontrollierten Notfall Zeit verschaffen, schafft aber keine Kapazität.

Überprüfen Sie die Zuweisungseinstellungen:

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

Wenn cluster.routing.allocation.enable auf none gesetzt ist, ist die Zuweisung deaktiviert. Dies ist häufig nach Wartungsskripten der Fall, die vergessen haben, sie wieder zu aktivieren. Aktivieren Sie sie erneut mit:

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

Überprüfen Sie auch, ob der Wert als transient gesetzt wurde; sowohl persistente als auch transiente Einstellungen können das Verhalten beeinflussen.

Roter Cluster-Playbook

Bei rotem Health verlangsamen Sie und identifizieren Sie den Schadensradius. Beginnen Sie nicht mit allocate_empty_primary. Dieser Befehl akzeptiert Datenverlust per Design.

Finden Sie zuerst die betroffenen Primär-Shards:

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

Dann untersuchen Sie einen mit Allocation Explain:

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

Wenn der Primär-Shard nicht zugewiesen ist, weil ein Knoten ausgefallen ist, besteht die beste Wiederherstellung möglicherweise darin, diesen Knoten wiederherzustellen. Überprüfen Sie den Dienst, die Festplatte, die JVM-Protokolle und den Netzwerkpfad. Wenn eine Replikatkopie auf einem anderen Knoten existiert, sollte Elasticsearch diese normalerweise hochstufen. Wenn nicht, sagen Ihnen die Explain-Ausgabe und die Protokolle normalerweise, warum.

Wenn die Daten verloren oder beschädigt sind, stellen Sie sie aus einem Snapshot wieder her. Das ist der saubere Wiederherstellungspfad. Wenn kein Snapshot existiert und die Daten aus einer anderen Quelle neu aufgebaut werden können, können Sie sich entscheiden, einen leeren Primär-Shard zuzuweisen:

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
        }
      }
    ]
  }'

Verwenden Sie dies nur, wenn der Verlust der Shard-Inhalte akzeptabel ist. Der Name ist wörtlich zu nehmen: Elasticsearch weist einen leeren Primär-Shard zu und fährt fort.

Beobachten Sie die Wiederherstellung anstatt zu raten

Nach einer Behebung beobachten Sie die Shard-Bewegung:

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"

Die Wiederherstellung kann durch Festplattengeschwindigkeit, Netzwerkbandbreite, Shard-Größe und Cluster-Wiederherstellungseinstellungen begrenzt werden. Ein großer Shard kann länger als erwartet im Zustand INITIALIZING verharren. Das ist etwas anderes als festzustecken. Wenn Byte-Zahlen und Datei-Zahlen in _cat/recovery sich bewegen, lassen Sie es arbeiten.

Überprüfen Sie auch ausstehende Cluster-Aufgaben, wenn sich der Health nicht ändert:

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

Eine lange Warteschlange kann auf einen überlasteten Master-Knoten oder wiederholte Zuweisungsentscheidungen hinweisen, die nicht abgeschlossen werden können.

Ein praktisches Beispiel

Angenommen, _cat/health zeigt gelb mit zwei nicht zugewiesenen Shards. _cat/shards zeigt, dass beide Replikate für logs-2026.05.24 sind. Allocation Explain sagt, dass der Cluster nicht zuweisen kann, weil jeder Datenknoten über dem niedrigen Festplatten-Watermark liegt. Die Lösung ist nicht, Shards manuell umzuleiten. Die Lösung ist Kapazität: Löschen Sie alte Indizes nach der Erstellung von Snapshots, fügen Sie Speicher hinzu, fügen Sie Datenknoten hinzu oder verschieben Sie kalte Daten woanders hin.

Ein weiteres Beispiel: Ein Drei-Knoten-Cluster ist nach einem rollierenden Neustart gelb. _cluster/health zeigt delayed_unassigned_shards: 8. Der gestoppte Knoten kommt bereits zurück. In diesem Fall kann das Warten einiger Minuten richtig sein. Das sofortige Erzwingen der Zuweisung kann zusätzliche Wiederherstellungsarbeit verursachen und den Neustart verlangsamen.

Ein drittes Beispiel: Ein Einzelknoten-Lab-Cluster ist für immer gelb. _cat/shards zeigt, dass jeder nicht zugewiesene Shard ein Replikat ist. Der Index hat ein Replikat. Elasticsearch verhält sich korrekt. Setzen Sie die Replikate für das Labor auf Null oder fügen Sie einen zweiten Datenknoten hinzu.

Halten Sie die Health-Überprüfung ehrlich

Der Cluster-Health sollte Teil des Monitorings sein, aber Alarmregeln benötigen Kontext. Alarmieren Sie sofort bei rot. Alarmieren Sie bei gelb, wenn es über ein kurzes Wartungsfenster hinaus anhält, wenn nicht zugewiesene Replikate zunehmen oder wenn der Grund Festplattendruck ist. Verfolgen Sie Festplatten-Watermarks, Knotenanzahl, JVM-Druck und Snapshot-Erfolg zusammen mit der Health-Farbe. Die Farbe sagt Ihnen, wo Sie anfangen sollen; die Shard- und Allocation-APIs sagen Ihnen, was als nächstes zu tun ist.

Wenn Health-Überprüfungen nicht mit Benutzersymptomen übereinstimmen

Manchmal ist der Cluster grün und Benutzer beschweren sich trotzdem. Das ist kein Widerspruch. Der Cluster-Health betrifft die Shard-Zuweisung, nicht die Abfragelatenz oder -korrektheit. Wenn der Health grün ist, aber Suchen langsam sind, wechseln Sie zu Suchlatenz, Thread-Pools, heißen Shards, JVM-Druck und Speicherlatenz. Ein grüner Cluster mit einem überlasteten Datenknoten kann sich trotzdem kaputt anfühlen.

Das Gegenteil passiert auch. Ein Cluster kann aus einem harmlosen Grund gelb sein, wie z. B. einer Einzelknoten-Entwicklungsumgebung mit konfigurierten Replikaten. Die nützliche Gewohnheit ist, den Health-Zustand mit den geschäftlichen Auswirkungen zu verbinden. Welcher Index ist betroffen? Ist es ein Primär-Shard oder ein Replikat? Liest die Anwendung gerade aus diesem Index? Findet dies während einer geplanten Wartung statt? Diese Fragen verhindern, dass Sie jeden gelben Status wie eine Katastrophe behandeln.

Für kundenorientierte Systeme behalte ich gerne eine kleine Runbook-Tabelle außerhalb von Elasticsearch: Index-Muster, verantwortlicher Dienst, Datenquelle, Snapshot-Richtlinie, ob Daten wiederholt werden können und wer eine destruktive Wiederherstellung genehmigt. Während eines roten Vorfalls ist diese Tabelle oft nützlicher als ein weiteres Dashboard. Wenn clickstream-* von Kafka wiederholt werden kann, ist die Wiederherstellungswahl anders als bei einem Index, der benutzergenerierte Dokumente ohne upstream-Kopie enthält.

Sicherere Befehlgewohnheiten

Verwenden Sie explizite Indexnamen, wenn möglich. Wildcards sind praktisch, aber sie verbergen den Schadensradius. Bevor Sie einen Befehl ausführen, der Einstellungen ändert oder Daten löscht, listen Sie auf, was das Muster matcht:

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

Bewahren Sie die Befehlsausgabe des Vorfalls auf. Fügen Sie Allocation-Explain-Ergebnisse, Shard-Listen und Health-Antworten in das Ticket ein. Der Elasticsearch-Zustand ändert sich während der Wiederherstellung schnell, und Sie benötigen möglicherweise die frühere Ausgabe, um zu verstehen, warum eine Entscheidung getroffen wurde.

Wenn Sicherheit aktiviert ist, führen Sie diese Befehle mit einem Benutzer aus, der die minimal nützlichen Berechtigungen für die Diagnose hat, und einem separaten, stärker eingeschränkten Prozess für destruktive Operationen. In einem stressigen Vorfall ist es zu einfach, einen Schreibbefehl in dieselbe Shell einzufügen, in der Sie nur den Health überprüft haben.

Was nach der Rückkehr des Clusters zu Grün zu überprüfen ist

Grün ist nicht das Ende des Vorfalls. Überprüfen Sie, ob Replikate auf den erwarteten Knoten neu aufgebaut wurden, ob die Festplatte immer noch nahe an den Watermarks ist und ob ein Index mit temporären Einstellungen wie number_of_replicas: 0, einem langen refresh_interval oder deaktivierter Zuweisung zurückgelassen wurde.

Bestätigen Sie auch, dass Snapshots nach der Wiederherstellung erfolgreich sind. Ein Cluster, der gerade Shard-Probleme hatte, kann eine Lücke in der Aufbewahrung, den Repository-Anmeldeinformationen oder der Snapshot-Planung offengelegt haben. Wenn die Wiederherstellung auf Glück beruhte, weil kein Snapshot existierte, schreiben Sie das auf und beheben Sie es vor dem nächsten Ausfall.

Überprüfen Sie schließlich die Alarme. Wenn Menschen das Problem bemerkt haben, bevor das Monitoring es tat, fügen Sie Alarme hinzu oder passen Sie sie an für roten Health, langanhaltenden gelben Health, Festplatten-Watermark-Druck, fehlende Knoten, fehlgeschlagene Snapshots und wiederholte Master-Wahlen. Eine Cluster-Health-Farbe ist nützlich, aber der beste Alarm sagt Ihnen, warum sich die Farbe geändert hat und welcher Index betroffen ist.