Circuit Breaker in Elasticsearch: Out-of-Memory-Fehler proaktiv verhindern

1. Warum Elasticsearch überhaupt Circuit Breaker braucht

Die JVM, auf der Elasticsearch läuft, arbeitet mit einem fest konfigurierten Heap-Speicher, dessen Größe beim Start des Node-Prozesses festgelegt wird. Überschreitet der tatsächliche Speicherbedarf diesen konfigurierten Heap, kann die JVM mit einem Out-of-Memory-Fehler abstürzen, was für den betroffenen Node einen unkontrollierten Neustart samt Shard-Recovery bedeutet, statt lediglich eine einzelne, überzogene Anfrage abzulehnen.

Ohne eine vorgelagerte Schutzschicht könnte bereits eine einzelne, schlecht konzipierte Aggregation oder Sortierung auf einem ungeeigneten Feld genug Speicher belegen, um den gesamten Node zum Absturz zu bringen und damit potenziell auch andere, völlig unabhängige Anfragen und Shards auf demselben Node in Mitleidenschaft zu ziehen. Circuit Breaker verhindern genau dieses Szenario, indem sie den geschätzten Speicherbedarf vor der eigentlichen Ausführung prüfen.

2. Der Parent Circuit Breaker als übergeordnete Guard-Rail

Der Parent Circuit Breaker bildet die oberste Grenze für den gemeinsamen, geschätzten Speicherverbrauch aller einzelnen Breaker zusammen und ist standardmäßig auf etwa 95 Prozent des konfigurierten JVM-Heaps eingestellt. Er greift, sobald die Summe aus Field-Data-, Request-, In-Flight-Requests- und weiteren Breakern diese Gesamtgrenze überschreitet, unabhängig davon, ob ein einzelner Breaker für sich genommen noch innerhalb seines eigenen Limits liegt.

Diese übergeordnete Grenze fängt insbesondere Fälle ab, in denen mehrere, für sich genommen unauffällige Operationen gleichzeitig ausgeführt werden und in Summe trotzdem den verfügbaren Heap überlasten würden. Ein einzelner, isoliert betrachteter Breaker-Wert allein reicht deshalb für eine vollständige Speicherdiagnose oft nicht aus, der Parent-Breaker-Status gehört immer mit ins Bild.

3. Field-Data-Breaker: Risiko bei Sortierung und Aggregation auf Text-Feldern

Der Field-Data-Breaker schützt vor übermäßigem Speicherverbrauch durch Field Data, jene In-Memory-Datenstruktur, die für Sortierungen, Aggregationen und Skript-Zugriffe auf analysierte Text-Felder benötigt wird, sofern kein geeignetes Keyword-Feld oder Doc-Values verwendet werden. Field Data muss für jedes betroffene Feld vollständig in den Heap geladen werden und wächst dabei proportional zur Anzahl der eindeutigen Terme im jeweiligen Feld.

In Magento-Kontexten tritt dieser Fall typischerweise auf, wenn versehentlich auf einem analysierten Textfeld wie einer Produktbeschreibung sortiert oder aggregiert wird, statt auf dem dafür vorgesehenen, nicht analysierten Keyword-Subfeld. Weil Field Data standardmäßig für Text-Felder deaktiviert ist, führt ein solcher Versuch meist zunächst zu einer expliziten Fehlermeldung, statt stillschweigend den Heap zu belasten, was das Problem in der Praxis früh sichtbar macht.

4. Request-Breaker: Schutz vor einzelnen teuren Anfragen

Der Request-Breaker schätzt den Speicherbedarf einer einzelnen Anfrage bereits während ihrer Ausführung, etwa für den Aufbau großer Aggregations-Buckets oder umfangreicher Sortierstrukturen, und bricht die Anfrage ab, sobald die geschätzte Speicherlast das konfigurierte Limit übersteigt. Anders als der Field-Data-Breaker betrifft er nicht nur Text-Feld-Zugriffe, sondern grundsätzlich jede Operation, die während der Ausführung signifikanten, temporären Speicher innerhalb einer einzelnen Anfrage benötigt.

Typische Auslöser sind Aggregationen mit sehr hoher Kardinalität, etwa eine Terms-Aggregation über ein Feld mit hunderttausenden eindeutigen Werten ohne sinnvolle Begrenzung der Bucket-Anzahl, oder tief verschachtelte Aggregationen mit vielen Ebenen, deren Speicherbedarf sich mit jeder zusätzlichen Ebene multipliziert. Ein ausgelöster Request-Breaker ist damit oft ein direkter Hinweis auf eine unpassend formulierte, zu wenig eingegrenzte Aggregation.

5. In-Flight-Requests-Breaker: Schutz vor Netzwerk-Puffer-Überlastung

Der In-Flight-Requests-Breaker überwacht den Speicherbedarf aller aktuell empfangenen, aber noch nicht vollständig verarbeiteten Transport- und HTTP-Anfragen. Er schützt damit vor einem Szenario, in dem sehr viele, gleichzeitig eintreffende Anfragen mit großen Payloads, etwa Bulk-Indexierungsanfragen mit großen Batch-Größen, gemeinsam so viel Pufferspeicher belegen, dass der Node ins Straucheln gerät, noch bevor die eigentliche Verarbeitung überhaupt begonnen hat.

Dieser Breaker ist besonders relevant bei hoher Indexierungslast, etwa während eines vollständigen Magento-Katalog-Reindex mit vielen parallelen Bulk-Requests. Wird dieser Breaker regelmäßig ausgelöst, ist häufig eine Reduzierung der Bulk-Batch-Größe oder der Anzahl gleichzeitiger Indexer-Threads die naheliegende Gegenmaßnahme, statt vorschnell das Breaker-Limit selbst zu erhöhen.

6. Typische Auslöser in Magento-Kontexten

Neben Sortierungen auf analysierten Textfeldern und hochkardinalen Aggregationen treten in Magento-Betrieb häufig noch zwei weitere Muster auf: unbegrenzte Facetten-Aggregationen in der Layered Navigation bei Kategorien mit sehr vielen unterschiedlichen Attributwerten, sowie sehr breite Scripted-Metric-Aggregationen für individuelle Preisberechnungen, die für jedes einzelne Dokument einen eigenen Skript-Kontext im Speicher aufbauen.

Auch ein plötzlicher Anstieg gleichzeitig ausgeführter, komplexer Facetten-Anfragen während eines Traffic-Peaks, etwa an einem Aktionstag, kann in Summe den Parent Circuit Breaker auslösen, selbst wenn jede einzelne Anfrage für sich genommen unauffällig wäre. Solche Lastspitzen sind ein guter Anlass, die Aggregations-Struktur der Layered Navigation grundsätzlich auf sinnvolle Bucket-Limits zu überprüfen.

7. Diagnose eines ausgelösten Circuit Breakers

Ein ausgelöster Circuit Breaker erzeugt eine klar erkennbare CircuitBreakingException in den Logs sowie in der HTTP-Antwort an den Client, inklusive Angabe des ausgelösten Breaker-Typs, des geschätzten Speicherbedarfs und des konfigurierten Limits. Diese Information ist der erste und wichtigste Ansatzpunkt, um die genaue Ursache einzugrenzen, statt pauschal von einem allgemeinen Speicherproblem auszugehen.

Die Nodes-Stats-API liefert zusätzlich pro Node und pro Breaker-Typ detaillierte Zähler, unter anderem die Anzahl der bisher ausgelösten Breaker-Ereignisse und den aktuell geschätzten Speicherverbrauch je Breaker. Ein kontinuierlicher Anstieg dieser Zähler über mehrere Tage hinweg deutet auf ein strukturelles Problem hin, ein einzelner, isolierter Ausschlag dagegen eher auf eine konkrete, schlecht formulierte Einzelanfrage.

# Breaker-Statistiken aller Nodes abfragen
curl "localhost:9200/_nodes/stats/breaker?pretty" \
  | jq '.nodes[].breakers | to_entries[] | {name: .key, tripped: .value.tripped}'

8. Tuning der Breaker-Limits: wann und wie vorsichtig anpassen

Die Standardwerte der einzelnen Circuit Breaker sind bewusst konservativ gewählt und sollten nicht als erste Reaktion auf einen ausgelösten Breaker pauschal erhöht werden, da eine Erhöhung lediglich den Sicherheitsabstand zum tatsächlichen Out-of-Memory-Fehler verkleinert, ohne das eigentliche, speicherintensive Anfragemuster zu beheben.

Eine moderate, gut begründete Anpassung ist sinnvoll, wenn Diagnose und Monitoring eindeutig zeigen, dass die Node-Hardware tatsächlich mehr Heap zur Verfügung hat, als die aktuellen Limits ausnutzen, und die auslösenden Anfragen bereits geprüft und als grundsätzlich notwendig eingestuft wurden. In diesem Fall werden die Limits über die Cluster-Settings-API schrittweise und mit engmaschiger Beobachtung angepasst, nie in einem großen Sprung.

PUT _cluster/settings
{
  "persistent": {
    "indices.breaker.request.limit": "50%",
    "indices.breaker.fielddata.limit": "30%"
  }
}

9. Präventive Maßnahmen statt reines Limit-Tuning

Nachhaltiger als das Anheben von Breaker-Limits ist die konsequente Vermeidung speicherintensiver Anfragemuster von vornherein: Sortierungen und Aggregationen ausschließlich auf Keyword-Feldern oder dedizierten Doc-Values-Feldern statt auf analysiertem Text, sowie sinnvolle, explizite Größenbegrenzungen bei jeder Terms- oder Composite-Aggregation.

Zusätzlich hilft ein regelmäßiger Blick in die Slow-Query-Logs, um Anfragemuster frühzeitig zu erkennen, die potenziell zu einem ausgelösten Breaker führen können, noch bevor sie unter realer Last tatsächlich eskalieren. Diese präventive Haltung reduziert die Notwendigkeit, die Breaker-Limits überhaupt anzufassen, und hält damit den eingebauten Sicherheitsabstand zur JVM-Speichergrenze vollständig erhalten.

10. Zusammenfassung

11. FAQ: Circuit Breaker in Elasticsearch: Das Wichtigste auf einen Blick