Circuit Breaker
Ein Circuit Breaker wickelt Calls, die fehlschlagen könnten (ein flakey HTTP-Endpoint, eine langsame DB-Query, ein Ask an einen kämpfenden Actor), und kurzschließt, wenn der Fehler anhält. Drei Zustände bilden eine einfache State-Machine:
- Closed (Start): Calls gehen durch; Fehler werden gezählt.
- Open: Calls schlagen sofort mit
CircuitBreakerOpenErrorfehl; kein Traffic erreicht den Downstream. - Half-open: Der erste Call nach dem Reset-Timeout wird durchgelassen. Erfolg → Closed. Fehler → wieder Open.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“import { CircuitBreaker, CircuitBreakerOpenError } from 'actor-ts';
const breaker = new CircuitBreaker({ maxFailures: 5, // nach 5 aufeinanderfolgenden Fehlern öffnen resetTimeoutMs: 30_000, // versuche eine Probe nach 30s callTimeoutMs: 2_000, // jeder Call > 2s zählt als Fehler});
try { const data = await breaker.call(() => fetch('https://flaky.example/items')); // closed → Call durchgelassen} catch (e) { if (e instanceof CircuitBreakerOpenError) { // Breaker ist open — versuche den Upstream gar nicht erst } else { // entweder ist der Call selbst fehlgeschlagen oder es gab einen Timeout }}Der Breaker kümmert sich nicht darum, was der Call ist — überall,
wo du eine Funktion hast, die ein Promise<T> zurückgibt, kannst
du sie wickeln. Für Actor-zu-Actor-Calls wickle ein ask:
const breaker = new CircuitBreaker({ maxFailures: 3, resetTimeoutMs: 10_000 });
async function askWithBreaker(): Promise<Reply> { return breaker.call(() => target.ask({ kind: 'q' }, 5_000));}Die State-Machine im Detail
Abschnitt betitelt „Die State-Machine im Detail“Closed → Open
Abschnitt betitelt „Closed → Open“Das Ergebnis jedes Calls aktualisiert einen Zähler:
- Erfolg setzt den Fehler-Zähler auf 0 zurück.
- Fehler inkrementiert ihn. Wenn der Zähler
maxFailuresaufeinanderfolgend erreicht, übergeht der Breaker zu Open und zeichnet auf, wann er als nächstes eine Probe erlaubt (now + resetTimeoutMs).
Was als Fehler zählt:
- Das Promise rejected.
- Der Call überschreitet
callTimeoutMs(falls konfiguriert) — der Breaker rejected mitCircuitBreakerTimeoutErrorund zählt es als Fehler. - Optional: Wenn
isFailure(err)falsezurückgibt, umgeht der Fehler die Zählung (das Promise rejected immer noch zum Aufrufer, aber der Breaker inkrementiert nicht). Verwende das für “das ist nicht wirklich ein Service-Fehler”-Fehler — 404s, Validierungsfehler, etc.
new CircuitBreaker({ maxFailures: 5, resetTimeoutMs: 30_000, isFailure: (err) => !(err instanceof ValidationError),});Die Optionen werden bei der Konstruktion validiert: ein fehlendes oder
nicht-positives maxFailures, ein negatives resetTimeoutMs oder ein
nicht-positives callTimeoutMs wirft OptionsError (lasse
callTimeoutMs ganz weg, um den Per-Call-Timeout zu deaktivieren).
Fehler über ihren Namen ignorieren
Abschnitt betitelt „Fehler über ihren Namen ignorieren“isFailure ist ein Prädikat und lebt damit im Code.
ignoredErrorNames ist dieselbe Idee als Daten ausgedrückt — eine
Liste von Error.name-Werten, die nie zählen — und genau das erlaubt
es dem Betrieb, sie in application.conf zu ändern, ohne zu deployen:
new CircuitBreaker({ maxFailures: 5, resetTimeoutMs: 30_000, ignoredErrorNames: ['ValidationError', 'NotFoundError'],});Die Liste wird vor isFailure geprüft, und ein gelisteter Name ist
nie ein Fehler, was das Prädikat auch sagt. Diese Reihenfolge ist
Absicht: die Liste ist die Hälfte des Klassifikators, die dem Betrieb
gehört, das Prädikat die des Entwicklers — könnte ein einkompiliertes
Prädikat die Liste überstimmen, liefe der Config-Key genau in den
Deployments ins Leere, die ihn gesetzt haben. Für einen nicht
gelisteten Namen entscheidet weiterhin isFailure.
'CircuitBreakerTimeoutError' ist listbar und bedeutet genau, was da
steht: ein Call, der seinen eigenen callTimeoutMs gerissen hat, zählt
nicht gegen den Breaker. Stimmig — „langsam ist nicht tot“ — und
überraschend genug, dass es beim Deployment, das sich dafür
entscheidet, notiert gehört.
Open → Half-open
Abschnitt betitelt „Open → Half-open“Sobald Open, rejected jeder Call sofort mit
CircuitBreakerOpenError. Der Breaker bleibt Open, bis seine Uhr — die
Wanduhr oder der scheduler, den er bekommen hat — nextProbeAt erreicht.
Zu dem Zeitpunkt übergeht der nächste Call zu Half-open und wird
durchgelassen. Das ist kein geplantes Aufwachen — der Breaker prüft lazy
beim nächsten call().
Die Ablehnung sagt, wie viel übrig ist: error.remainingMs ist die
Wartezeit ab der Ablehnung, bis ein Call durchgelassen würde. Ein Aufrufer,
der wiederkommen will, liest das statt nextProbeAt, denn nur der Breaker
weiß, auf welcher Uhr der Zeitstempel steht.
Half-open → Closed (oder zurück zu Open)
Abschnitt betitelt „Half-open → Closed (oder zurück zu Open)“Der Probe-Call entweder:
- Gelingt → Breaker schließt. Zähler zurücksetzen. Normalbetrieb.
- Schlägt fehl → Breaker öffnet wieder mit frischem
nextProbeAt.
Während Half-open ist nur die eine Probe im Flug. Parallele Calls während Half-open gehen auch durch (der Breaker serialisiert nicht), aber die Zustands-Übergänge des Breakers werden vom ersten Vollenden getrieben.
Der Reopen-Fahrplan
Abschnitt betitelt „Der Reopen-Fahrplan“Standardmäßig ist das Fenster flach: jedes Öffnen wartet
resetTimeoutMs. Zwei optionale Stellschrauben ändern das, und beide
sind neutral ausgeliefert, damit das Default-Verhalten das jedes
früheren Releases bleibt.
const breaker = new CircuitBreaker({ maxFailures: 5, resetTimeoutMs: 15_000, // the first window backoffFactor: 2, // each further open doubles it maxResetTimeoutMs: 60_000, // …up to here randomFactor: 0.2, // then spread by ±20%});Die Verzögerung für das n-te aufeinanderfolgende Öffnen ist
resetTimeoutMs × backoffFactor^(n − 1), begrenzt auf
maxResetTimeoutMs, anschließend mit 1 ± randomFactor
multipliziert. Oben also 15 s, 30 s, 60 s, 60 s …, jeweils ±20 %.
Der Zähler fällt zurück, sobald eine Probe gelingt und der Breaker
schließt — eine Dependency, die sich erholt, beginnt wieder beim
ersten Fenster statt in einem langen zu bleiben, das sie sich im
Ausfall verdient hat.
Ein resetTimeoutMs von 0 — „beim unmittelbar nächsten Call
proben“ — bleibt bei jeder Öffnungszahl 0, gleich welcher Faktor:
das Wachstum ist multiplikativ, und es gibt nichts zu multiplizieren.
Die Kombination ist zulässig und bleibt es; das Fenster ist für jede
zulässige Kombination dieser vier Einstellungen eine endliche
Millisekundenzahl, wie lange der Ausfall auch dauert.
Der Jitter folgt demselben Vertrag wie bei retry und
exponentialBackoff und bringt hier dasselbe: N Repliken, die auf
ein und dasselbe Upstream-Ereignis hin geöffnet haben, proben nicht
mehr im Gleichschritt, und die sich erholende Dependency trifft eine
gestreute Folge von Proben statt einer synchronisierten Welle.
maxResetTimeoutMs begrenzt das gesamte Fenster, nicht nur das
Wachstum — ein resetTimeoutMs oberhalb der Grenze wird deshalb bei
der Konstruktion abgelehnt statt still gekürzt: stilles Kürzen
ersetzte ein Fenster, das der Betrieb gewählt hat, durch eines, das
niemand aufgeschrieben hat. Der Default sind 60 s, und genau die muss
ein längeres resetTimeoutMs anheben.
breaker.nextProbeAt liest den geplanten Zeitstempel,
breaker.consecutiveOpens den Exponenten dahinter — so sieht eine
Metrik den Fahrplan, ohne ihn abwarten zu müssen.
Breaker aus der Konfiguration
Abschnitt betitelt „Breaker aus der Konfiguration“new CircuitBreaker({ … }) ist die Tür für einen Breaker, dessen
Settings im Code stehen. Die CircuitBreakerExtension ist die
andere: sie löst einen Breaker über seine Id auf, die Zahlen kommen
also aus HOCON, und die Instanz gehört dem System statt dem, was sie
erzeugt hat.
import { CircuitBreakerExtensionId } from 'actor-ts';
const breakers = system.extension(CircuitBreakerExtensionId);const payments = breakers.breaker('payment-api');const shipping = breakers.breaker('shipping-api');actor-ts.circuit-breaker { default { max-failures = 5 reset-timeout = 15s } payment-api { max-failures = 3 reset-timeout = 30s backoff-factor = 2.0 random-factor = 0.2 ignored-error-names = ["ValidationError"] }}payment-api nimmt seine eigenen vier Blätter und erbt den Rest von
default; shipping-api hat gar keinen Block und ist vollständig der
default-Block. Jede Id ist eine eigene Instanz mit eigenen Settings
— das ist der Rat „ein Breaker pro logischer Abhängigkeit“ weiter
unten, konfigurierbar gemacht statt bloß empfohlen. Dieselbe Id
liefert immer dieselbe Instanz, und sie liest die Uhr des Systems — unter
einem ManualScheduler bewegt sich ihr Fenster mit dem Vorrücken.
Die eigenen Breaker des Frameworks werden genauso aufgelöst und deshalb im
selben Block konfiguriert: Die Persistence-Stores benennen ihre mit
actor-ts.persistence.journal-breaker / snapshot-breaker, und ein
Broker-Actor benennt einen mit withCircuitBreaker('kafka') oder
circuit-breaker = "kafka" unter seinem Root — aus, bis er es tut. Jeder
Actor, der dieselbe Id nennt, teilt sich die Instanz: ein Breaker pro
Broker-Cluster, geöffnet von irgendeinem von ihnen, mit höchstens einem Versuch
pro Fenster von jedem — und einer einzigen Probe für alle nur so lange, wie ein
fehlschlagender Connect kurz ist gegenüber der Streuung ihres Aufwachens (siehe
BrokerActor-Basis).
Was eine Config-Datei nicht ausdrücken kann, wird als zweites Argument übergeben und sticht beide Blöcke:
const payments = breakers.breaker('payment-api', { isFailure: (err) => err.name !== 'ValidationError',});Gelesen wird es einmal, beim Erzeugen der Instanz — ein späteres
breaker('payment-api') liefert den bereits existierenden Breaker
zurück, statt ihn neu zu konfigurieren. Ein schlechter Wert in einem
der beiden Blöcke wirft bei genau diesem ersten Aufruf OptionsError,
ein vertippter Override scheitert also laut, statt einen Breaker still
auf den Framework-Defaults laufen zu lassen.
Ein Klassifikator, der zur Abhängigkeit gehört, nicht zu einem Aufrufer
Abschnitt betitelt „Ein Klassifikator, der zur Abhängigkeit gehört, nicht zu einem Aufrufer“Diese „einmal gelesen“-Regel hat eine scharfe Kante, sobald mehr als
eine Stelle dieselbe Id auflöst: wer zuerst da ist, entscheidet, und
das isFailure jedes späteren Aufrufers fällt still unter den Tisch.
Das Prädikat stattdessen an call zu übergeben umgeht das — es
klassifiziert die Fehler dieses Calls und sticht das, womit die
Instanz gebaut wurde:
const journal = breakers.breaker('persistence-journal');
await journal.call( () => store.append(id, entries, expectedSeq), (err) => !(err instanceof ConcurrencyError),);Nimm die Konstruktions-Option, wenn die Settings des Breakers dir
allein gehören, und das Per-Call-Argument, wenn die Id geteilt oder
veröffentlicht ist — genau das tut das Framework für
actor-ts.persistence.journal-breaker, dessen Id ein dokumentierter
Config-Pfad ist, den jeder auflösen darf.
Die Persistenz-Breaker wählen den Klassifikator außerdem pro Aufruf,
weil nicht jeder Aufruf durch sie einer ist, den sie schützen. Ein
Append, eine Recovery und das Laden eines Snapshots werden wie oben
klassifiziert; das Löschen im Journal und das Speichern oder Löschen
eines Snapshots laufen weiterhin durch den Breaker — call-timeout
begrenzt sie also, und ein offener Breaker weist sie ab —, aber mit
einem Klassifikator, der nichts zählt. Ein Store, der Löschen oder
Snapshot-Schreibvorgänge verweigert, alles andere aber bedient, kann
deshalb nicht den Breaker vor jedem Append und jeder Recovery auf dem
Knoten öffnen; siehe Wenn die Stores
ausfallen.
ignoredErrorNames kommt in beiden Fällen zuerst, und ein
entschuldigter Fehler ist weiterhin weder Fehler noch Erfolg: der
Zähler aufeinanderfolgender Fehler überlebt ihn unverändert, ein
entschuldigter Fehler zwischen je zwei echten kann den Breaker also
nicht daran hindern, sich zu öffnen.
Die vollständige Key-Liste steht in der Konfigurations-Referenz.
Observability
Abschnitt betitelt „Observability“import { CircuitBreaker, type CircuitState } from 'actor-ts';import { MetricsExtensionId } from 'actor-ts/metrics';
const breaker = new CircuitBreaker({ maxFailures: 5, resetTimeoutMs: 30_000 });
// A gauge holds a number, so the state is encoded — ordered by how much// traffic is refused, the encoding persistence_breaker_state uses too.const stateValue: Record<CircuitState, number> = { closed: 0, 'half-open': 1, open: 2 };const metrics = system.extension(MetricsExtensionId).enable();const stateGauge = metrics.gauge( 'payments_breaker_state', {}, { help: 'Payments API circuit breaker: 0 closed, 1 half-open, 2 open.' },);stateGauge.set(stateValue[breaker.state]);
const unsubscribe = breaker.onStateChange((state) => { stateGauge.set(stateValue[state]); log.info(`circuit breaker → ${state}`);});
// Later: `unsubscribe()` to remove.Verwende das, um Zustands-Übergänge in deine Logging- oder
Metriken-Pipeline zu verdrahten. Der Listener feuert bei jedem
Übergang, einschließlich erzwungener via breaker.setState(...).
metrics.gauge(name, labels, options) gibt das Gauge zurück; es ist
kein Setter, der Wert geht also über .set(). Der Name muss ein
Prometheus-Metrikname sein — Unterstriche, keine Punkte — und ein
Gauge hält eine Zahl, deshalb wird der Zustand abgebildet statt
durchgereicht. Ein set vor dem ersten Übergang sorgt dafür, dass
ein geschlossener Breaker als 0 erscheint statt im Scrape zu
fehlen.
breaker.state liest den aktuellen Zustand synchron.
Die beiden Breaker vor den Persistence-Stores brauchen nichts davon:
bei aktivierten Metriken werden sie als
persistence_breaker_state{breaker="journal"|"snapshot"} exportiert —
siehe Persistenz-Metriken.
Der Breaker eines Broker-Actors braucht es ebenso wenig: Jeder Actor, der
einen nennt, publisht dessen Übergänge auf dem Event-Stream als
BrokerCircuitBreakerStateChanged.
Manuelle Overrides
Abschnitt betitelt „Manuelle Overrides“breaker.setState('open'); // Open erzwingen — nützlich für Admin "drain diese Dep"breaker.setState('closed'); // Closed erzwingen — manuelles RecoverysetState ist meist für Tests und Admin-Endpoints. Production-Code
sollte sich auf den natürlichen Übergangspfad verlassen; zu
setState aus regulärem Code zu greifen, bedeutet meist, dass der
Breaker nicht richtig konfiguriert ist.
Die Zahlen wählen
Abschnitt betitelt „Die Zahlen wählen“Drei Parameter entscheiden, wann der Breaker auslöst; so denkst du über sie:
maxFailures— hoch genug, dass ein einzelner transienter Aussetzer den Breaker nicht öffnet, niedrig genug, dass ein echter Ausfall ihn öffnet, bevor zu viel Traffic sich staut. 3-10 ist typisch. Niedriger für kritische Pfade (schnell öffnen); höher für Pfade, wo Falsch-Auslösungen teuer sind.resetTimeoutMs— lang genug, damit der Downstream sich erholen kann, aber kurz genug, dass du es bemerkst, wenn er es hat. 10-60 Sekunden für typische HTTP-/DB-Calls; sub-Sekunde nur, wenn der Breaker eine wirklich lokale Ressource frontet.callTimeoutMs— das längste, das der einzelne Call brauchen sollte. Wenn die p99 des Upstreams 800 ms ist, setze das auf 2-3 s. Es niedriger als die normale Latenz des Upstreams zu setzen, bedeutet, dass du alles zu einem Timeout erklärst.
Drei weitere formen den Reopen-Fahrplan, und alle drei sind standardmäßig aus:
backoffFactor— bei1lassen für eine Dependency, deren Ausfälle kurz sind und sich von selbst klären; zu2greifen, wenn ein wiederholt fehlschlagender Upstream einer ist, den du seltener fragen solltest. Das Wachstum akkumuliert nur, solange der Breaker nie schließt, kostet im Normalfall also nichts.maxResetTimeoutMs— wie lange du bereit bist, eine Erholung nicht zu bemerken. Muss mindestensresetTimeoutMssein; der Default von 60 s ist die Obergrenze, auf die sich der Rest des Projekts für einen Backoff geeinigt hat, hinter dem jemand wartet.randomFactor—0.2, wenn mehr als ein Prozess diesen Breaker gegen dieselbe Dependency fährt,0, wenn es genau einer ist. Jitter geht darum, eine Flotte zu entkoppeln, und eine einzelne Instanz hat nichts, wovon sie sich entkoppeln müsste.
Verglichen mit Retry
Abschnitt betitelt „Verglichen mit Retry“Ein Breaker und ein Retry-Helfer sind komplementär, kein Ersatz:
- Retry sagt “versuche es nach einer Verzögerung erneut, wenn dieser Call fehlschlägt.” Er behandelt jeden Call unabhängig und brennt sein Budget für die aktuelle Operation.
- Breaker sagt “nach genug neuesten Fehlern, hör eine Weile auf zu versuchen.” Er trägt Zustand über Calls hinweg.
Die richtige Kombination ist Retry innerhalb eines Breaker-Calls:
breaker.call(() => retry( () => fetch('https://flaky.example'), { attempts: 3, delayMs: 100, factor: 2 },));Der Retry handhabt die Per-Call-Resilienz; der Breaker handhabt
die “Hör auf, die kaputte Dep zu hämmern”-Koordination. Lege den
Retry nicht außerhalb des Breakers — du würdest durch die
CircuitBreakerOpenErrors retrien, was sinnlos ist.
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Retry — der komplementäre Per-Call-Retry-Helfer.
- Backoff-Supervisor — Exponential-Backoff-Restarts für ein Child eines Actors.
- Ask-Pattern — was du typischerweise wickelst, wenn der Call Actor-zu-Actor ist.
Die CircuitBreaker-API-Referenz
deckt die volle Schnittstelle ab.
