Cluster-Health-Monitoring und Alerting sauber aufsetzen

1. Warum green/yellow/red allein nicht reicht

Der _cluster/health Endpunkt liefert mit dem Status green, yellow oder red die bekannteste Kennzahl fuer Cluster-Health-Monitoring. Viele Teams richten ihr gesamtes Alerting ausschliesslich auf diesen einen Wert aus, was aber ein trueglerisches Sicherheitsgefuehl erzeugt: der Status wechselt oft erst auf yellow oder red, wenn ein Problem bereits Auswirkungen auf die Verfuegbarkeit hat, nicht wenn es entsteht. Ein Cluster, der stundenlang mit stark steigendem Heap-Druck laeuft, bleibt formal green, bis der erste Node abstuerzt.

Wirksames Cluster-Health-Monitoring braucht deshalb zusaetzliche, feinkoernigere Metriken, die auf sich anbahnende Probleme hinweisen, bevor sie den Gesamtstatus beeinflussen. Unassigned Shards, Heap-Auslastung, Queue-Rejections und Node-Verfuegbarkeit sind vier Kennzahlen, die zusammen ein deutlich fruehzeitigeres Bild liefern als der reine Health-Status. Ziel ist es, auf Trends zu reagieren, nicht nur auf bereits eingetretene Ausfaelle.

Dieser Beitrag ordnet die wichtigsten Signale fuer Cluster-Health-Monitoring nach Dringlichkeit und zeigt konkrete API-Aufrufe, um sie automatisiert abzufragen und in Alerting-Regeln zu ueberfuehren, unabhaengig davon, ob Prometheus, die Elastic Stack eigenen Watcher oder ein externes Monitoring-Tool zum Einsatz kommt.

2. Der _cluster/health Status im Detail

Der Status green bedeutet, dass alle Primary- und Replica-Shards zugeteilt sind. Yellow bedeutet, dass alle Primary Shards verfuegbar sind, aber mindestens ein Replica Shard nicht zugeteilt werden konnte, meist weil nicht genug Data-Nodes fuer die konfigurierte Replica-Anzahl vorhanden sind. Red bedeutet, dass mindestens ein Primary Shard nicht verfuegbar ist, was fuer die betroffenen Indizes direkten Datenverlust bei Leseanfragen bedeutet, solange der Zustand anhaelt.

Ein haeufiger Fehler im Cluster-Health-Monitoring ist, yellow generell als unkritisch einzustufen. Ein einzelner Testindex ohne Replica-Konfiguration, der dauerhaft yellow ist, unterscheidet sich fundamental von einem produktiven Index, der ploetzlich yellow wird, weil ein Data-Node ausgefallen ist. Alerting sollte deshalb nicht nur auf den globalen Status reagieren, sondern auf Statusaenderungen und auf pro-Index-Health, verfuegbar ueber _cluster/health?level=indices.

GET _cluster/health?level=indices

// Global status can be yellow while individual indices are still red,
// per-index detail is essential for correct alert prioritization
{
  "cluster_name": "production-logs",
  "status": "yellow",
  "number_of_nodes": 9,
  "active_primary_shards": 142,
  "unassigned_shards": 3,
  "indices": {
    "orders-2026.07": { "status": "green", "number_of_shards": 3, "unassigned_shards": 0 },
    "sessions-2026.07": { "status": "yellow", "number_of_shards": 5, "unassigned_shards": 3 }
  }
}

3. Unassigned Shards: Ursachen und Diagnose

Unassigned Shards sind eine der wichtigsten Einzelmetriken im Cluster-Health-Monitoring, weil sie fast immer ein konkretes, diagnostizierbares Problem anzeigen. Die haeufigsten Ursachen: ein Node ist ausgefallen und seine Shards muessen neu zugeteilt werden, die Disk-Watermark-Schwelle wurde auf einem Node ueberschritten, sodass Elasticsearch aus Sicherheitsgruenden keine neuen Shards mehr dorthin verteilt, oder Allocation-Filter-Regeln verhindern eine gueltige Zuteilung, etwa durch eine falsch konfigurierte Shard-Allocation-Awareness.

Die _cluster/allocation/explain API ist das zentrale Diagnosewerkzeug fuer unassigned Shards: sie liefert den genauen Grund, warum ein bestimmter Shard nicht zugeteilt werden konnte, statt dass man raten muss. Ein gutes Cluster-Health-Monitoring-Setup ruft diese API automatisch auf, sobald die Anzahl unassigned Shards ueber einen Schwellwert von null steigt, und haengt die Antwort direkt an den Alert an, um Diagnosezeit im Ernstfall zu sparen.

GET _cluster/allocation/explain
{
  "index": "sessions-2026.07",
  "shard": 2,
  "primary": false
}

// Response reveals the concrete blocking reason instead of forcing a guess
{
  "index": "sessions-2026.07",
  "shard": 2,
  "primary": false,
  "current_state": "unassigned",
  "unassigned_info": {
    "reason": "NODE_LEFT",
    "at": "2026-07-24T03:14:22.000Z"
  },
  "allocate_explanation": "cannot allocate because a previous copy of the primary shard existed but can no longer be found"
}

4. Heap-Druck als Fruehwarnsignal

Heap-Auslastung ist die wichtigste Fruehwarnmetrik im Cluster-Health-Monitoring, weil sie oft steigt, lange bevor ein Node tatsaechlich instabil wird. Die _nodes/stats API liefert den Heap-Fuellstand pro Node in Prozent. Als grobe Alerting-Schwelle hat sich ein Warnwert bei fuenfundsiebzig Prozent anhaltender Auslastung und ein kritischer Wert ab fuenfundachtzig Prozent etabliert, wobei "anhaltend" entscheidend ist: kurze Spitzen nach einem Garbage-Collection-Zyklus sind normal, ein Wert, der auch nach mehreren GC-Zyklen nicht sinkt, ist es nicht.

Fuer belastbares Cluster-Health-Monitoring reicht ein einzelner Momentwert nicht aus. Sinnvoller ist ein gleitender Durchschnitt ueber mehrere Minuten, kombiniert mit der Anzahl der Garbage-Collection-Zyklen im selben Zeitraum. Steigt die GC-Frequenz gleichzeitig mit der Heap-Auslastung, ist das ein deutlich staerkeres Signal fuer ein echtes Speicherproblem als ein einzelner hoher Prozentwert.

5. Queue-Rejections aus Thread-Pools

Jeder Thread-Pool in Elasticsearch, etwa fuer Search, Write oder Bulk, hat eine begrenzte Warteschlangenlaenge. Wenn mehr Anfragen ankommen, als der Pool verarbeiten und die Queue aufnehmen kann, werden weitere Anfragen mit einem Rejection-Fehler abgelehnt, statt unbegrenzt zu warten. Diese Rejections sind fuer Cluster-Health-Monitoring ein direktes, unmissverstaendliches Signal dafuer, dass der Cluster mehr Last erhaelt, als er aktuell verarbeiten kann.

Anders als Heap-Druck, der graduell entsteht, sind Queue-Rejections binaer: entweder eine Anfrage wird abgelehnt oder nicht, und jede Ablehnung bedeutet einen konkreten Fehler beim aufrufenden Client. Ein Alert auf rejected > 0 im relevanten Thread-Pool ist deshalb eine der direktesten Alerting-Regeln ueberhaupt, ohne Interpretationsspielraum bei der Schwellwertwahl.

GET _nodes/stats/thread_pool/write,search,bulk

// A non-zero "rejected" counter means clients received real errors,
// this is one of the clearest possible alert conditions
{
  "nodes": {
    "abc123": {
      "thread_pool": {
        "write": { "threads": 8, "queue": 42, "active": 8, "rejected": 17 },
        "search": { "threads": 13, "queue": 3, "active": 5, "rejected": 0 },
        "bulk": { "threads": 8, "queue": 0, "active": 2, "rejected": 0 }
      }
    }
  }
}

6. Weitere Metriken fuer belastbares Monitoring

Neben den drei Kernmetriken gehoeren weitere Kennzahlen in ein vollstaendiges Cluster-Health-Monitoring: Disk-Watermark-Auslastung pro Node, da Elasticsearch bei ueberschrittener High-Watermark aktiv Shards von einem Node entfernt, was zu unassigned Shards fuehrt, wenn kein Ziel mit ausreichend Platz existiert. Die Anzahl der pendenten Cluster-State-Tasks, ueber _cluster/pending_tasks, zeigt an, ob Master-Node-Operationen wie Shard-Zuteilungen sich stauen, ein Indiz fuer einen ueberlasteten Master.

Segment-Merge-Zahlen und Indexierungslatenz sind fuer datenintensive Cluster ebenfalls relevant, allerdings eher fuer Performance- als fuer reines Verfuegbarkeitsmonitoring. Fuer den Einstieg in Cluster-Health-Monitoring reicht es, sich zunaechst auf Health-Status, unassigned Shards, Heap-Druck und Queue-Rejections zu konzentrieren, und das Monitoring anschliessend schrittweise um weitere Metriken zu erweitern, je nachdem, welche Vorfaelle im Betrieb tatsaechlich auftreten.

# elasticsearch.yml - default disk watermark thresholds, adjust with care
cluster.routing.allocation.disk.watermark.low: 85%
cluster.routing.allocation.disk.watermark.high: 90%
cluster.routing.allocation.disk.watermark.flood_stage: 95%

# Above flood_stage, indices on the affected node are forced read-only
# until free disk space drops back below the threshold again

7. Alerting-Regeln richtig priorisieren

Nicht jede Abweichung im Cluster-Health-Monitoring verdient dieselbe Reaktionsgeschwindigkeit. Ein Cluster-Status red mit betroffenen Primary Shards braucht sofortige Reaktion rund um die Uhr, waehrend ein einzelner kurzzeitiger Heap-Spike auf einem Node meist als niedriger priorisierter Hinweis fuer die naechste Arbeitswoche ausreicht. Eine dreistufige Priorisierung, etwa kritisch, warnend und informativ, verhindert Alert-Fatigue und sorgt dafuer, dass wirklich dringende Meldungen nicht in einer Flut weniger relevanter Benachrichtigungen untergehen.

Wichtig fuer nachhaltiges Cluster-Health-Monitoring ist auch die zeitliche Dimension: die meisten Metriken sollten nicht auf einen einzelnen Messpunkt reagieren, sondern auf anhaltende Zustaende ueber ein definiertes Zeitfenster. Ein kurzer Heap-Spike waehrend eines geplanten Snapshot-Vorgangs ist normal, derselbe Wert ueber fuenfzehn Minuten hinweg nicht. Diese Unterscheidung reduziert Fehlalarme erheblich, ohne echte Probleme zu uebersehen.

8. Werkzeuge fuer Cluster-Health-Monitoring

Fuer die technische Umsetzung von Cluster-Health-Monitoring gibt es mehrere etablierte Wege: der Elasticsearch-Exporter fuer Prometheus exponiert die relevanten Metriken in einem Format, das sich direkt in Grafana visualisieren und mit Alertmanager verknuepfen laesst. Alternativ bietet die Elastic Stack selbst mit Kibana Stack Monitoring und Watcher eine integrierte Loesung, die ohne zusaetzliche Infrastruktur auskommt, aber an eine Lizenzstufe gebunden ist.

Fuer kleinere Setups reicht oft ein einfaches Skript, das die relevanten APIs periodisch abfragt und bei Schwellwertueberschreitung eine Benachrichtigung ausloest, etwa per Webhook an Slack oder PagerDuty. Wichtiger als das gewaehlte Werkzeug ist bei Cluster-Health-Monitoring, dass die Metriken konsistent erfasst und die Alerting-Schwellen regelmaessig gegen die tatsaechliche Cluster-Groesse und Workload ueberprueft werden, statt einmal gesetzte Werte unveraendert zu lassen.

9. Eskalationsstufen und Runbooks

Ein Alert allein loest kein Problem, deshalb gehoert zu gutem Cluster-Health-Monitoring immer ein dokumentiertes Runbook: fuer jeden kritischen Alert-Typ sollte festgehalten sein, welche Diagnoseschritte als erstes auszufuehren sind, etwa _cluster/allocation/explain bei unassigned Shards, und welche Sofortmassnahmen in Frage kommen, etwa das manuelle Ausloesen einer Shard-Neuzuteilung oder das temporaere Anheben einer Disk-Watermark in einer Notfallsituation.

Eskalationsstufen sollten klar definieren, wann ein automatisierter Alert ausreicht und wann ein Mensch informiert werden muss, idealerweise mit unterschiedlichen Kanaelen je nach Dringlichkeit: informative Hinweise in ein Monitoring-Dashboard, warnende Signale in einen Team-Chat, kritische Alerts in ein On-Call-System mit garantierter Zustellung. Diese Struktur macht Cluster-Health-Monitoring erst wirklich handlungsfaehig, statt nur Daten zu sammeln, die niemand rechtzeitig sieht.

PUT _watcher/watch/critical_unassigned_shards
{
  "trigger": { "schedule": { "interval": "1m" } },
  "input": {
    "http": { "request": { "host": "localhost", "port": 9200, "path": "/_cluster/health" } }
  },
  "condition": {
    "compare": { "ctx.payload.unassigned_shards": { "gt": 0 } }
  },
  "actions": {
    "notify_oncall": {
      "webhook": {
        "method": "POST",
        "host": "hooks.example.com",
        "path": "/oncall-critical",
        "body": "Unassigned shards detected, run _cluster/allocation/explain immediately"
      }
    }
  }
}

10. Zusammenfassung

Wirksames Cluster-Health-Monitoring geht ueber den einfachen green/yellow/red Status hinaus und beobachtet unassigned Shards, Heap-Auslastung und Queue-Rejections als zentrale Fruehwarnsignale. Die _cluster/allocation/explain API liefert konkrete Diagnosegruende statt Vermutungen, waehrend Thread-Pool-Statistiken direkt anzeigen, wenn der Cluster mehr Last erhaelt, als er verarbeiten kann. Anhaltende Zustaende ueber ein Zeitfenster sind aussagekraeftiger als einzelne Momentwerte.

Der letzte, oft vernachlaessigte Baustein ist die Priorisierung: nicht jeder Alert braucht eine sofortige Reaktion, aber jeder kritische Alert-Typ braucht ein dokumentiertes Runbook mit klaren Diagnose- und Reaktionsschritten. Wer Cluster-Health-Monitoring so aufbaut, erkennt Probleme, bevor sie zu Ausfaellen werden, statt nur im Nachhinein zu rekonstruieren, was schiefgelaufen ist.

11. FAQ: Cluster-Health-Monitoring und Alerting