Zum Inhalt springen
Deutsch

Health Checks

Die Management-Routen exponieren zwei Health-Endpunkte:

  • GET /health — Liveness. Liefert 200, wenn der Prozess betriebsbereit ist.
  • GET /ready — Readiness. Liefert 200, wenn der Pod bereit ist, Traffic zu empfangen.

Beide aggregieren eine Registry pro ActorSystem, erreichbar über healthChecksOf(system). Framework-Komponenten registrieren sich dort beim Start; deine eigenen Checks kommen auf dasselbe Objekt:

import { healthChecksOf, managementRoutes } from 'actor-ts/management';
const health = healthChecksOf(system);
health.addReadiness(async () => {
const ok = await database.ping();
return { name: 'database', status: ok, detail: ok ? undefined : 'database unreachable' };
});
health.addReadiness(async () => {
try {
await cache.ping();
return { name: 'cache', status: true };
} catch (e) {
return { name: 'cache', status: false, detail: (e as Error).message };
}
});
await system.http(8558).bind(managementRoutes(system, cluster));

Wenn irgendein Check status: false zurückgibt, liefert der entsprechende Endpunkt 503 mit einem JSON-Body, der das Ergebnis jedes Checks auflistet.

Diese registriert das Framework selbst — du bekommst sie, ohne danach zu fragen, und sie liegen in der Aggregation, die /ready liest. Der gRPC-Dienst grpc.health.v1.Health liest die Registry, die du ihm übergibst: reiche healthChecksOf(system) durch, und beide können nie unterschiedlicher Meinung darüber sein, was „ready” heißt — eine frische HealthCheckRegistry an dieser Stelle trennt sie.

CheckArtRegistriert vonSchlägt fehl, wenn
actor-systemLivenessder Registry selbstsystem.terminate() durchgelaufen ist
cluster-membershipReadinessCluster.joindieser Knoten in seiner eigenen Member-Sicht nicht up ist
cluster-transportReadinessCluster.joinder Knoten keinen der noch erwarteten Peers erreichen kann
startupReadinessder Registry selbst, wenn das System Startup-Tasks hatder Startup-Graph noch läuft oder einer seiner Tasks fehlgeschlagen ist
shard-region:<type>ReadinessCluster.join, einer pro Typ in actor-ts.sharding.healthcheck.namesdie Region dieses Knotens für den Typ nicht beim Koordinator registriert ist — siehe Auf eine Shard-Region warten

startup gibt es nur auf einem System mit Startup-Tasks, und der Check bleibt, wenn der Start vorbei ist: von da an true, oder false mit dem fehlgeschlagenen Task und seinem Fehler im detail. Solange der Graph läuft, nennt detail die Phase, in der er gerade ist.

cluster-transport prüft absichtlich auf vollständige Isolation und nicht auf „jeder Peer ist erreichbar”. Eine Teilpartition lässt den Knoten weiter gossippen, konvergieren und routen — ihn aus dem Load Balancer zu nehmen würde einem Cluster Kapazität entziehen, der die Lage beherrscht. Vom ganzen Cluster abgeschnitten zu sein ist der Fall, in dem Weiterbedienen zur Split-Brain-Gefahr wird — und der Fall, den ein Knoten aus seiner Member-Sicht allein nicht sehen kann, weil kein Peer den eigenen Datensatz dieses Knotens herabstufen darf. Ein Ein-Knoten-Cluster erwartet niemanden und besteht immer.

Die Peers, die er noch erwartet, sind die Mitglieder außer diesem Knoten, die weder down noch removed sind — unreachable inklusive — mit einer Ausnahme: ein Peer, den dieser Knoten über down-after hinaus geparkt hat, weil keine Downing-Strategie konfiguriert und failure-detector.auto-down aus ist. Einen geparkten Peer entfernt nichts, auf ihn zu warten hielte den Knoten also für immer aus der Rotation. Ein Überlebender, dessen einziger Peer abgestürzt ist, ist deshalb aus der Rotation, solange dieser Peer bloß unreachable ist, und bei down-after wieder bereit, wie auch immer das Deployment sich entschieden hat: Unter dem Default auto-down = on wird der tote Peer dann entfernt, unter dem Opt-out auto-down = off wird er dann geparkt. Die Peer-Zahlen im detail des Checks lassen einen geparkten Peer genauso weg. Ein geparkter Peer, der wieder Heartbeats schickt, wird wieder erwartet. Ein Peer, der unreachable ist, aber down-after noch nicht erreicht hat, zählt weiterhin, sodass ein kurzer Aussetzer einen allein verbliebenen Überlebenden wie bisher aus der Rotation nimmt, und ebenso ein Peer, über den eine konfigurierte Downing-Strategie noch entscheidet, bis sie entschieden hat.

„Erreichbar” heißt eine offene Verbindung zu einem Peer, den der Failure Detector noch nicht abgeschrieben hat — und es braucht beide Hälften. Ein offener Socket allein beweist nichts: Die kanonische Partition — iptables -j DROP, eine schwarz gelochte Route, ein hängender Peer — nimmt den Verkehr weg, ohne ein FIN oder ein RST zu erzeugen. Die Sockets bleiben also aufgebaut, solange der Kernel es weiter versucht, während überhaupt nichts mehr ausgetauscht wird. Zu verlangen, dass der Peer auch erreichbar ist, übergibt dieses Urteil dem Failure Detector — der Komponente, die Stille bemerkt.

Was der Check nicht erkennt, damit du damit planen kannst:

  • die Latenz des Failure Detectors selbst — zwischen Beginn der Partition und dem Auslösen des Detectors meldet sich der Knoten weiter als ready. Das ist dasselbe Zeitfenster, in dem der Rest des Clusters reagiert.
  • eine Einweg-Partition, bei der dieser Knoten noch empfängt. Seine Peers sehen weiter Up aus, er sieht also weiter ready aus, während nichts von dem ankommt, was er sendet. Das zu erkennen bräuchte einen quittierten Roundtrip.

cluster.leave() lässt beide Checks registriert und fehlschlagend zurück — /ready antwortet für den Rest der Prozesslaufzeit mit 503, und genau das drainiert einen Pod, bevor er stoppt. Nichts im Framework entfernt einen Readiness-Check auf dem Weg aus dem Betrieb: Eine leere Aggregation gilt als gesund (siehe unten), Abmelden würde also „alles besteht” und „es meldet nichts mehr” zur selben Antwort machen. Ein späteres Cluster.join auf demselben System zieht das alte Paar zurück und installiert sein eigenes; ein Prozess, der verlässt und wieder beitritt, erholt sich also normal — Sharding eingeschlossen: Das Verlassen stoppt die Regionen und Koordinatoren, die der Knoten gestartet hat, sodass der neue Cluster dieselben Typen wieder starten kann.

Ein Knoten, der einen geshardeten Typ hostet, kann ihn erst bedienen, wenn seine Region beim Koordinator registriert ist — und die Member-Konvergenz sagt nicht, ob sie es ist: Die Region registriert sich beim Koordinator auf dem Leader, über einen eigenen Retry-Timer. Nenne die Typen, ohne die der Knoten nicht bereit ist:

actor-ts.sharding.healthcheck.names = ["orders", "billing"]

Cluster.join installiert dann pro Name einen Readiness-Check shard-region:<type> neben den beiden des Clusters — ab dem Join, nicht erst ab dem ersten cluster.sharding.start(...), sodass ein Knoten, der einen genannten Typ nie startet, aus der Rotation bleibt, statt sich bereit zu melden. Jeder Check besteht, sobald cluster.sharding.isRegistered(type) es tut, und sein detail sagt, welcher von drei Gründen ihn rot hält:

  • keine Region läuft für den Typ auf diesem Knoten — sie wurde hier nie gestartet, oder sie ist gestoppt, was das Verlassen des Clusters tut;
  • der Koordinator hat sie abgelehnt, wegen number-of-shards, mit beiden Zahlen;
  • die Region läuft und ist noch nicht bestätigt — nach ihrem Start, nachdem der Koordinator sie entfernt hat, und nachdem ein Leader-Wechsel eine Ablehnung aufgehoben hat.

Ein Leader-Wechsel allein färbt keinen Check rot. Der Check liest, was die Region dieses Knotens zuletzt gesagt bekommen hat, und ein neuer Leader sagt ihr nichts, bis sein Koordinator antwortet: Eine registrierte Region registriert sich im Hintergrund beim neuen Koordinator und bleibt dabei durchgehend grün.

Ein abgelehnter Knoten bleibt aus der Rotation, bis number-of-shards übereinstimmt. Das ist eine Entscheidung, keine Nebenwirkung: Eine abgelehnte Region nimmt weiter Traffic für den Typ an und puffert ihn vollständig, weil ihr nie ein Shard zugeteilt wird — den Knoten aus dem Load Balancer zu nehmen ist das Einzige, was hilft. Es gibt bewusst kein Fenster, nach dem der Check aufgibt, und keinen Timeout: Der Check schlägt nur in einer Menge nach, es gibt nichts, worauf er warten müsste, und nach einer Frist zu bestehen würde genau diesen Knoten zurück in die Rotation bringen.

Eine Ablehnung ist das Urteil der Amtszeit eines Leaders. Ein Leader-Wechsel hebt sie auf: Das detail lautet läuft und ist noch nicht bestätigt, bis der nächste Koordinator antwortet, und dieser entscheidet neu — er nimmt die Region an, wenn die Zahlen mit seinen eigenen übereinstimmen, und lehnt sie ab, wenn nicht.

Wie die beiden des Clusters bleiben die Checks über leave() hinweg registriert, und ein späteres Cluster.join zieht sie mit dem Paar zurück. Für einen Typ, den nur der Code kennt, registrierst du denselben Check selbst:

import { healthChecksOf, shardRegionRegistered } from 'actor-ts/management';
healthChecksOf(system).addReadiness(shardRegionRegistered(cluster, 'orders'));
type HealthCheckFunction = () => Promise<HealthCheckResult> | HealthCheckResult;
type HealthCheckResult = {
name: string; // identifies the check in the response
status: boolean; // true = healthy
detail?: string; // human-readable note, usually on failure
};

Ein Check kann sync oder async sein. addLiveness / addReadiness geben jeweils eine Unsubscribe-Funktion zurück — rufe sie auf, um den Check wieder zu entfernen:

const remove = health.addReadiness(() => ({ name: 'warmup', status: warmedUp }));
// ... once warm-up is permanently done:
remove();

Lang laufende Checks blockieren die Antwort, halte sie also schnell (unter einer Sekunde, idealerweise < 100 ms).

ProbeWas sie beantwortetWas K8s bei Fehlschlag tut
Liveness (/health)„Würde ein Neustart dieses Prozesses helfen?”Pod neu starten.
Readiness (/ready)„Soll ein Load Balancer diesem Pod Traffic schicken?”Kein Routing mehr hierher (Pod läuft weiter).

Ob ein Check Liveness oder Readiness ist, entscheidet welche Methode du aufrufst — addLiveness oder addReadiness. Es sind getrennte Listen; wer denselben Check für beides will, registriert ihn zweimal.

Der Unterschied ist keine Geschmacksfrage — er entscheidet, was in welche Liste darf:

  • Liveness darf von nichts außerhalb dieses Prozesses abhängen. Ein fehlschlagender Liveness-Check lässt den Pod töten; ein Check, der bei einem kurzen Aussetzer einer gemeinsam genutzten Datenbank rot wird, macht aus dem Ausfall einer Abhängigkeit einen flottenweiten Neustart-Sturm — und die Neustarts reparieren nichts. Deshalb ist der einzige Liveness-Check des Frameworks „das Actor-System ist nicht heruntergefahren”.
  • Readiness ist genau der richtige Ort für das, was Liveness nicht anfassen darf — die Abhängigkeiten, die ein Request braucht. Sie nimmt den Knoten aus der Rotation und lässt ihn laufen; ein Datenbank-Aussetzer, ein sich füllender Cache oder ein Cluster-Rejoin gehören hierher.

Eine Readiness-Probe, die 200 liefert, obwohl der Knoten nicht erreichen kann, was er braucht, ist schlimmer als gar keine Probe: sie nimmt weiter Traffic an, den sie nicht bedienen kann.

/ready meldet neben der Check-Liste ein Flag clusterReady. Es ist das Ergebnis des cluster-membership-Checks selbst, aus der Aggregation zurückgelesen statt separat berechnet — Flag und Check können sich also nie widersprechen. Es ist false, bis der lokale Knoten den Zustand Up erreicht, und immer true auf einem System, das nie einem Cluster beigetreten ist:

GET /ready
→ 503
{
"status": "DOWN",
"clusterReady": false,
"checks": [
{ "name": "cluster-membership", "status": false, "detail": "this node is 'joining' in its own member view, not 'up'" },
{ "name": "cluster-transport", "status": true }
]
}

Das prozessinterne Gegenstück ist cluster.awaitReady() / cluster.isReady() — dieselbe up-only-Mitgliedschaftssemantik, aus Code awaited statt über HTTP abgefragt (siehe Cluster-Bootstrap → Auf Readiness warten). Die beiden sind bewusst nicht gekoppelt: awaitReady schaut allein auf die Mitgliedschaft, nie auf das Readiness-Aggregat, denn app-registrierte Checks bestehen unter Umständen erst nach Initialisierung, die nach dem Bootstrap läuft — von innerhalb Cluster.bootstrap auf sie zu warten könnte den Start verklemmen. /ready bleibt die Sicht des Load Balancers.

health.addReadiness(databaseCheck);
health.addReadiness(cacheCheck);
health.addReadiness(downstreamApiCheck);

Alle Readiness-Checks laufen parallel, wenn /ready aufgerufen wird. Die Antwort listet das Ergebnis jedes Checks:

{
"status": "DOWN",
"clusterReady": true,
"checks": [
{ "name": "cluster-membership", "status": true },
{ "name": "cluster-transport", "status": true },
{ "name": "database", "status": false, "detail": "connection refused" },
{ "name": "cache", "status": true },
{ "name": "downstream-api", "status": true }
]
}

Die Aggregation ist UP, wenn der status jedes Checks true ist.

Keine Checks zu registrieren ist die Aussage, dass nichts die Probe verriegelt. Ein System mit leerer Readiness-Liste antwortet also mit 200 — sonst wäre jeder einfache, clusterlose Dienst hinter managementRoutes sein Leben lang 503. /ready, /health und der gRPC-Health-Dienst wenden diese Regel über dieselbe exportierte Funktion an:

import { isHealthy } from 'actor-ts/management';
isHealthy([]); // true
isHealthy([{ name: 'database', status: false }]); // false

Sicher ist die Regel nur, weil nichts die Liste leert. Könnte eine Komponente sich beim Herunterfahren abmelden, wären „gesund” und „es meldet nichts mehr” nicht mehr unterscheidbar — eine Komponente, die verstummt, meldet stattdessen status: false und bleibt registriert. Nutze das Undo von addReadiness zum Ersetzen oder wenn das beobachtete Objekt abgebaut wird, nie als Störungssignal.

import { HealthCheckRegistry } from 'actor-ts/management';
it('readiness fails when the database is down', async () => {
const health = new HealthCheckRegistry();
health.addReadiness(async () => ({ name: 'database', status: false, detail: 'mock' }));
const results = await health.checkReadiness();
expect(results).toEqual([{ name: 'database', status: false, detail: 'mock' }]);
});

Ein blankes new HealthCheckRegistry() ist im Unit-Test genau richtig — es enthält nur, was der Test hineinlegt, ohne die Checks des Frameworks. In Produktion führt der Weg immer über healthChecksOf(system): eine zweite Registry ist eine zweite Vorstellung von „ready”, und nur eine davon lesen die Endpunkte.

checkLiveness() / checkReadiness() führen die registrierten Checks aus und geben das HealthCheckResult[] zurück, das die Endpunkte aggregieren — praktisch, um Checks isoliert zu testen. Ein Check, der wirft, wird abgefangen und als { name: 'unknown', status: false, detail } gemeldet. Der Helfer isHealthy(results) ist dasselbe „alle bestehen”-Prädikat, das auch die Endpunkte benutzen.

Jeder Check läuft gegen eine Deadline — standardmäßig eine Sekunde. Danach antwortet die Registry für diesen Check, und seine Geschwister melden weiterhin normal; eine hängende Abhängigkeit kostet also einen fehlschlagenden Eintrag statt der ganzen Antwort:

{
"status": "DOWN",
"checks": [
{ "name": "unknown", "status": false, "detail": "health check did not answer within 1000ms" },
{ "name": "cache", "status": true }
]
}

Der Name ist unknown, weil der Name im HealthCheckResult steckt, das der Check nie zurückgegeben hat — derselbe Fallback, den ein werfender Check schon immer erzeugt hat. Die Deadline steht im detail, dem einzigen Feld, das sie noch tragen kann.

Pro Knoten einstellbar:

actor-ts.management.health-checks.check-timeout = 500ms

Die Deadline gehört der Registry, nicht einem einzelnen Check: sie gilt für Liveness wie Readiness und ist eine Zahl, an der ein Operator drehen kann. Ein Check, der ein anderes Budget braucht, setzt weiterhin sein eigenes Rennen an:

health.addReadiness(async () => {
const status = await Promise.race([
slowProbe().then(() => true),
new Promise<boolean>((r) => setTimeout(() => r(false), 2_000)),
]);
return { name: 'downstream', status };
});

Diese Variante meldet einen Namen, was die Antwort der Registry nicht kann — für einen Check, von dem du weißt, dass er stehen bleiben kann, lohnt sie sich.

Halte Checks trotzdem schnell. Die Deadline hält die Antwort in Bewegung; sie stoppt nicht die Arbeit hinter einem Check, und sie liegt bewusst unter dem eigenen Probe-Timeout von K8s (timeoutSeconds, Standard 1 s), damit das Framework — und nicht der Orchestrator — sagen darf, welcher Check hängt. Erhöhe sie in einem Deployment, dessen Probe-Timeout tatsächlich höher liegt.