Zum Inhalt springen
Deutsch

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:

Fehler ≥ maxFailures

Reset-Timeout abgelaufen

Probe gelingt

Probe schlägt fehl

Closed\nCalls gehen durch

Open\nCalls schlagen schnell fehl

Half-open\nProbe-Call

  • Closed (Start): Calls gehen durch; Fehler werden gezählt.
  • Open: Calls schlagen sofort mit CircuitBreakerOpenError fehl; kein Traffic erreicht den Downstream.
  • Half-open: Der erste Call nach dem Reset-Timeout wird durchgelassen. Erfolg → Closed. Fehler → wieder Open.
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));
}

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 maxFailures aufeinanderfolgend 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 mit CircuitBreakerTimeoutError und zählt es als Fehler.
  • Optional: Wenn isFailure(err) false zurü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).

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.

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.

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.

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.

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.

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.

breaker.setState('open'); // Open erzwingen — nützlich für Admin "drain diese Dep"
breaker.setState('closed'); // Closed erzwingen — manuelles Recovery

setState 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.

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 — bei 1 lassen für eine Dependency, deren Ausfälle kurz sind und sich von selbst klären; zu 2 greifen, 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 mindestens resetTimeoutMs sein; 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.

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.

  • 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.