Performance-Troubleshooting: eine belastbare Checkliste

1. Warum systematische Diagnose planlosem Ausprobieren ueberlegen ist

Ein langsamer Elasticsearch-Cluster hat selten eine einzige, offensichtliche Ursache. Meist ist es eine Kombination aus mehreren Faktoren: eine ungewoehnlich teure Query, ein Node mit zu wenig Heap, eine unguenstige Shard-Verteilung oder ein temporaerer Spitzenload, der einen Thread-Pool ueberlastet. Wer bei einem Performance-Problem wahllos Einstellungen aendert, etwa die Heap-Groesse erhoeht oder Replikate reduziert, ohne die tatsaechliche Ursache verstanden zu haben, riskiert, das Symptom kurzfristig zu lindern, waehrend das eigentliche Problem beim naechsten Lastanstieg erneut auftritt.

Eine systematische Performance-Diagnose folgt stattdessen einer festen Reihenfolge: zuerst der grobe Ueberblick ueber Cluster-Health und Ressourcenauslastung, dann die gezielte Suche nach langsamen Operationen ueber Slow Log und Hot Threads API, gefolgt von der Pruefung auf strukturelle Engpaesse wie gestaute Pending Tasks oder abgelehnte Requests in ueberlasteten Queues. Diese Reihenfolge stellt sicher, dass offensichtliche, grobe Probleme zuerst ausgeschlossen werden, bevor Zeit in die Analyse subtilerer Ursachen investiert wird.

Dieser Artikel fasst die wichtigsten Diagnose-Werkzeuge zu einer praktischen Checkliste zusammen, die sich direkt im Ernstfall abarbeiten laesst, ergaenzt um konkrete API-Aufrufe und typische Interpretationen der Ergebnisse.

2. Schritt eins: Cluster-Health und Ressourcenauslastung pruefen

Der erste Blick bei jedem Performance-Problem gilt dem Cluster-Health-Status und der grundlegenden Ressourcenauslastung aller Nodes. Ein Status yellow oder red deutet auf fehlende oder nicht zugewiesene Shards hin, was oft direkt mit einem Performance-Einbruch korreliert, weil betroffene Anfragen auf weniger Kopien der Daten ausweichen muessen oder ganz fehlschlagen. Die Node-Statistiken zeigen ergaenzend CPU-Auslastung, Heap-Nutzung, Festplatten-I/O und freien Speicherplatz pro Node, oft reicht bereits dieser grobe Ueberblick, um einen einzelnen ueberlasteten Node als Ursache zu identifizieren.

Besonders wichtig ist der Blick auf Disk-Watermarks: Erreicht ein Node den High-Watermark fuer belegten Speicherplatz, blockiert Elasticsearch automatisch die weitere Shard-Zuweisung auf diesen Node, was zu einer unguenstigen, unausgewogenen Lastverteilung im gesamten Cluster fuehren kann. Dieser Zustand ist leicht zu uebersehen, weil der Cluster-Health-Status dabei oft noch green bleibt, obwohl die tatsaechliche Ressourcenverteilung bereits stark unausgewogen ist und einzelne Nodes deutlich staerker belastet sind als andere.

# Overall cluster health
curl -s "https://localhost:9200/_cluster/health?pretty" -u elastic:changeme

# Per-node resource usage: CPU, heap, disk
curl -s "https://localhost:9200/_cat/nodes?v&h=name,cpu,heap.percent,ram.percent,disk.used_percent" \
  -u elastic:changeme

# Check disk watermark thresholds currently configured
curl -s "https://localhost:9200/_cluster/settings?include_defaults=true&filter_path=**.disk.watermark*" \
  -u elastic:changeme

3. Slow Log: langsame Queries und Indexierungen identifizieren

Das Slow Log protokolliert Queries und Indexierungsvorgaenge, die eine konfigurierbare Zeitschwelle ueberschreiten, getrennt nach Such- und Indexierungs-Slow-Log sowie nach den Phasen Query und Fetch bei Suchvorgaengen. Ohne aktiviertes Slow Log bleibt unklar, welche konkreten Anfragen fuer eine hohe Performance-Belastung verantwortlich sind, da die allgemeinen Cluster-Metriken nur die Gesamtlast zeigen, nicht aber welche einzelne Query ungewoehnlich teuer ist.

Ein sinnvoller Schwellenwert fuer die Warn-Stufe liegt oft bei ein bis zwei Sekunden fuer die Query-Phase, abhaengig von den Latenzanforderungen der jeweiligen Anwendung. Zu niedrige Schwellenwerte fluten das Log mit Eintraegen und erschweren die Analyse, zu hohe Schwellenwerte lassen relevante, aber noch nicht extrem langsame Queries unentdeckt. Ein bewaehrtes Vorgehen ist, mit einem konservativen Schwellenwert zu starten und ihn schrittweise zu senken, bis das Slow Log ein handhabbares, aber aussagekraeftiges Volumen an Eintraegen liefert.

// Enable slow log thresholds for an index
PUT /products/_settings
{
  "index.search.slowlog.threshold.query.warn": "2s",
  "index.search.slowlog.threshold.query.info": "1s",
  "index.search.slowlog.threshold.fetch.warn": "500ms",
  "index.indexing.slowlog.threshold.index.warn": "2s",
  "index.indexing.slowlog.level": "info"
}

# Tail the slow log directly on a data node to see live entries
tail -f /var/log/elasticsearch/production_index_search_slowlog.log

# Grep for the slowest recent queries above a threshold
grep "took\[" production_index_search_slowlog.log | sort -t'[' -k2 -rn | head -20

4. Hot Threads API: CPU-Last auf Thread-Ebene verstehen

Waehrend das Slow Log zeigt, welche Queries langsam sind, zeigt die Hot Threads API, welche internen Threads eines Nodes gerade die meiste CPU-Zeit verbrauchen, inklusive eines Stacktrace-Ausschnitts, der die aktuell ausgefuehrte Operation erkennen laesst. Das ist besonders wertvoll, wenn CPU-Last auf einem Node hoch ist, aber unklar bleibt, ob die Ursache Suchanfragen, Indexierung, Merges oder interne Verwaltungsaufgaben wie Cluster-State-Updates sind.

Die Ausgabe der Hot Threads API zeigt Threads sortiert nach CPU-Anteil, mit Bezeichnungen wie search, write, oder [Lucene Merge Thread], die direkt auf die Ursache hindeuten. Ein hoher Anteil an Merge-Threads deutet auf eine Schreiblast hin, die mehr Segment-Merges erzeugt, als der Node bequem verarbeiten kann, waehrend ein hoher Anteil an Search-Threads auf teure oder zu haeufige Suchanfragen hindeutet. Die API laesst sich gezielt gegen einzelne oder alle Nodes ausfuehren und liefert typischerweise innerhalb weniger Sekunden ein aussagekraeftiges Bild der aktuellen CPU-Last.

# Hot threads across all nodes, sorted by CPU usage
curl -s "https://localhost:9200/_nodes/hot_threads?threads=5" -u elastic:changeme

# Hot threads for a single, specific node only
curl -s "https://localhost:9200/_nodes/node-data-03/hot_threads?threads=5" \
  -u elastic:changeme

5. Pending Tasks: Stau im Master-Node erkennen

Der Master-Node verarbeitet Cluster-State-Updates wie das Anlegen von Indizes, Mapping-Aenderungen oder Shard-Zuweisungen sequenziell in einer internen Warteschlange. Unter normalen Bedingungen ist diese Warteschlange leer oder enthaelt nur wenige Eintraege, die innerhalb von Millisekunden abgearbeitet werden. Wenn sich Pending Tasks anhaeufen, deutet das auf einen ueberlasteten Master-Node hin, oft verursacht durch sehr viele gleichzeitige Index-Erstellungen, ein zu grosses Cluster-State-Objekt bei sehr vielen Indizes und Shards, oder einen Master-Node, der zusaetzlich als Daten-Node ueberlastet ist.

Ein gestauter Master-Node wirkt sich indirekt auf die gesamte Cluster-Performance aus, weil jede Operation, die eine Cluster-State-Aenderung erfordert, etwa das Anlegen eines neuen taeglichen Log-Index, in der Warteschlange haengen bleibt, bis der Master-Node sie verarbeitet. Bei sehr grossen Clustern mit tausenden Indizes ist es deshalb eine bewaehrte Praxis, Master-Nodes als dedizierte, reine Master-Nodes ohne Datenrolle zu betreiben, damit sie nicht gleichzeitig durch Suchanfragen oder Indexierung belastet werden.

# List pending cluster state tasks, if any are queued up
curl -s "https://localhost:9200/_cluster/pending_tasks?pretty" -u elastic:changeme

# Cluster state size can indirectly explain a slow master node
curl -s "https://localhost:9200/_cluster/state/_all?pretty" -u elastic:changeme | wc -c

6. Queue Rejections: ueberlastete Thread-Pools aufspueren

Elasticsearch verarbeitet unterschiedliche Operationstypen, etwa Suche, Schreiben und Bulk-Indexierung, in separaten Thread-Pools mit jeweils begrenzter Groesse und begrenzter Warteschlange. Wenn mehr Anfragen eintreffen, als der Thread-Pool und seine Warteschlange aufnehmen koennen, lehnt Elasticsearch weitere Anfragen mit einem TOO_MANY_REQUESTS-Fehler ab, statt sie unbegrenzt zu puffern. Diese Ablehnungen, sichtbar in den Thread-Pool-Statistiken als rejected-Zaehler, sind ein direktes Signal fuer eine strukturelle Kapazitaetsgrenze, nicht nur eine voruebergehende Verlangsamung.

Ein steigender Rejection-Zaehler im Bulk-Thread-Pool deutet typischerweise darauf hin, dass Indexierungs-Clients mit einer zu grossen Bulk-Groesse oder zu hoher Parallelitaet gegen den Cluster schreiben. Die Loesung liegt selten darin, die Thread-Pool-Groesse einfach zu erhoehen, weil das die zugrunde liegende Ressourcenknappheit nur verschiebt, sondern meist darin, die Bulk-Groesse zu reduzieren, die Anzahl paralleler Indexierungs-Clients zu begrenzen, oder zusaetzliche Kapazitaet durch weitere Nodes bereitzustellen, wenn die grundlegende Last dauerhaft gestiegen ist.

# Thread pool statistics with rejection counters per pool
curl -s "https://localhost:9200/_cat/thread_pool/write,search,bulk?v&h=node_name,name,active,queue,rejected" \
  -u elastic:changeme

# Watch rejections increase over time (run repeatedly during load)
watch -n 5 'curl -s "https://localhost:9200/_cat/thread_pool/write?v&h=node_name,rejected" -u elastic:changeme'

7. Shard-Groesse und -Anzahl als strukturelle Ursache

Ueber akute Symptome hinaus ist eine unguenstige Shard-Groesse und Shard-Anzahl eine der haeufigsten strukturellen Ursachen fuer chronische Performance-Probleme. Zu viele kleine Shards erzeugen unnoetigen Verwaltungs-Overhead, da jeder Shard eigene Lucene-Dateihandles, Segment-Metadaten und einen eigenen Anteil am Cluster-State belegt. Zu grosse Shards hingegen verlangsamen Recovery-Vorgaenge nach einem Node-Ausfall und machen einzelne Suchanfragen langsamer, weil ein einzelner Shard nicht mehr innerhalb eines Threads parallelisiert werden kann.

Eine gaengige Faustregel empfiehlt Shard-Groessen zwischen 20 und 50 Gigabyte fuer die meisten Anwendungsfaelle, wobei die tatsaechlich optimale Groesse vom konkreten Query- und Indexierungsmuster abhaengt. Wird eine strukturelle Fehlplanung bei der Shard-Groesse als Ursache identifiziert, ist die Loesung meist ein Reindex in einen neu angelegten Index mit angepasster number_of_shards-Einstellung, kombiniert mit Index-Lifecycle-Management fuer zeitbasierte Indizes, das automatisch neue Indizes mit passender Groesse rotiert.

8. Garbage Collection und Heap-Druck als Sonderfall

Ein haeufig uebersehener Sonderfall ist Performance-Degradierung durch haeufige oder lange Garbage-Collection-Pausen der JVM. Ist der Heap eines Nodes chronisch ueber 75 bis 85 Prozent ausgelastet, greift der Garbage Collector immer haeufiger und mit laengeren Pausen ein, waehrend derer der betroffene Node keine Anfragen verarbeiten kann. Diese GC-Pausen erscheinen in der Cluster-Performance als sporadische, schwer reproduzierbare Latenzspitzen, die nicht direkt mit einer bestimmten Query korrelieren, was die Diagnose ohne gezielten Blick auf die GC-Logs erschwert.

Die GC-Logs eines Nodes zeigen Dauer und Haeufigkeit von Garbage-Collection-Zyklen direkt, und lange Young-Generation- oder gar Full-GC-Pausen von mehreren Sekunden sind ein klares Signal fuer chronischen Heap-Druck. Die Loesung liegt selten in einer pauschalen Heap-Vergroesserung ueber die empfohlenen 50 Prozent des verfuegbaren RAM oder ueber 30 bis 32 Gigabyte hinaus, weil das die Compressed-Oops-Optimierung der JVM deaktiviert und paradoxerweise die Performance verschlechtern kann, sondern meist in einer Reduktion der tatsaechlichen Heap-Last durch kleinere Aggregationsfenster, weniger gleichzeitige teure Queries oder zusaetzliche Nodes zur Lastverteilung.

9. Die vollstaendige Checkliste im Ueberblick

Zusammengefuehrt ergibt sich eine feste Abfolge fuer jede Performance-Diagnose: Cluster-Health und grobe Ressourcenauslastung pruefen, Slow Log auf konkrete langsame Operationen durchsuchen, bei hoher CPU-Last die Hot Threads API befragen, Pending Tasks auf Master-Node-Stau pruefen, Thread-Pool-Statistiken auf Rejections untersuchen, und bei chronischen Problemen Shard-Groesse sowie GC-Verhalten als strukturelle Ursachen in Betracht ziehen. Diese Reihenfolge deckt sowohl akute Vorfaelle als auch schleichende, strukturelle Verschlechterungen ab.

Der entscheidende Vorteil dieser Checkliste gegenueber Ad-hoc-Diagnose ist Reproduzierbarkeit: Jedes Teammitglied, das dieselbe Reihenfolge abarbeitet, kommt zu denselben Zwischenergebnissen und kann sie im Team nachvollziehbar dokumentieren, statt bei jedem Vorfall neu zu improvisieren. Ein dokumentiertes Runbook, das diese Checkliste als konkrete Befehlsfolge enthaelt, reduziert die Zeit bis zur Ursachenfindung im Ernstfall erheblich, gerade wenn der Vorfall unter Zeitdruck und moeglicherweise ausserhalb der regulaeren Arbeitszeit auftritt.

10. Zusammenfassung

Systematisches Performance-Troubleshooting fuer Elasticsearch und OpenSearch folgt einer festen Kette: Cluster-Health und Ressourcen zuerst, dann Slow Log fuer konkrete langsame Operationen, Hot Threads API fuer CPU-Last auf Thread-Ebene, Pending Tasks fuer Master-Node-Stau, Thread-Pool-Rejections fuer Kapazitaetsgrenzen, und bei chronischen Problemen Shard-Groesse sowie Garbage-Collection-Verhalten als strukturelle Ursachen. Diese Reihenfolge deckt sowohl akute als auch schleichende Probleme zuverlaessig ab.

Der groesste Hebel liegt darin, diese Checkliste vor dem naechsten Vorfall als dokumentiertes Runbook bereitzustellen, statt sie im Ernstfall erst zusammenzustellen. Ein Team, das diese Werkzeuge kennt und regelmaessig uebt, findet die Ursache eines Performance-Problems in Minuten statt Stunden, was in produktiven Umgebungen mit direktem Geschaeftseinfluss den entscheidenden Unterschied macht.

11. FAQ: Performance-Troubleshooting-Checkliste