Zum Inhalt springen
Deutsch

Shard-Introspektion

Eine Region zu starten gibt dir genau eine Ref — die der Region — und das war bisher die ganze Geschichte. Du konntest Nachrichten durch das Sharding schicken, aber es nichts fragen: nicht “welche Shards gibt es”, nicht “wo liegt Shard 7”, nicht “gib mir einen Handle auf Entity user-42”.

Vier APIs auf ClusterSharding schließen diese Lücke, dazu ein Cluster-Event für die Push-Seite.

shards(typeName) antwortet clusterweit, von jedem Node aus:

const shards = await cluster.sharding.shards<CounterCommand>('counter');
for (const shard of shards) {
console.log(
`shard ${shard.shardId} on ${shard.node}`,
`— ${shard.entityCount} entities`,
shard.local ? '(here)' : '',
);
}

Jeder Eintrag ist ein ShardInfo:

type ShardInfo<TMessage = unknown> = {
readonly shardId: number;
readonly node: NodeAddress; // node currently hosting the shard
readonly regionPath: string; // region on that node
readonly entityCount: number; // live entities when its region answered
readonly resident: boolean; // shard actor materialised at that moment
readonly local: boolean; // hosted by the node that asked
readonly ref: ActorRef<ShardMessage<TMessage>>;
};

resident unterscheidet einen Shard, der läuft und gerade leer ist, von einem, der leer passiviert wurde — entityCount: 0 meldet beides. Auf die Erreichbarkeit hat es keinen Einfluss: ref funktioniert so oder so. Lies es, wenn du shardPassivationIdleMs einstellst oder zählen willst, wie viele Actors ein Node tatsächlich hält.

Der Eintrag trägt eine lebende Ref, nicht nur Platzierungsdaten — eine Abfrage beantwortet also sowohl “was gibt es da draußen” als auch “wie rede ich damit”. Der Preis: ShardInfo ist nicht JSON-serialisierbar. Wenn du eine serialisierbare Sicht brauchst, nimm shardMap(typeName) oder den Management-Endpunkt GET /cluster/shards, der genau diese serialisiert.

Shards ohne Zuhause fehlen in der Liste. Niemand hat nach ihnen gefragt, also hatte der Koordinator keinen Anlass, sie zu platzieren: ein Typ mit 64 Shards, der drei Entity-IDs gesehen hat, meldet ein bis drei Shards, nicht 64.

Der Koordinator besitzt die Shard-Karte, aber nicht die Entity-Zahlen — die kennt nur die Region, die den Shard hostet. Der Aufruf fächert deshalb an alle registrierten Regions aus und joint die Antworten gegen die Allokationskarte. Also ein zusätzlicher Round-Trip.

Die Fan-out-Frist ist eine Teilantwort-Frist: eine Region, die zu langsam ist oder zwischen Karten-Schnappschuss und Fan-out gegangen ist, steuert entityCount: 0 bei, statt den ganzen Aufruf scheitern zu lassen. Du bekommst eine vollständige Shard-Liste mit einer konservativen Zahl, keine Exception.

shards() und shardRefFor() warten actor-ts.sharding.shard-region-query-timeout (5 s), oder was withShardRegionQueryTimeoutMs dem Typ mitgegeben hat, oder ein timeoutMs, das du als letztes Argument übergibst. Die Region behält eine wartende Abfrage eine Minute lang, oder so lange wie actor-ts.actor.ask-timeout oder der Query-Timeout des Typs, wenn einer davon länger ist — ein timeoutMs pro Aufruf sieht sie nicht. Ein timeoutMs über dieser Lebensdauer wird also nicht voll ausgewartet: Eine Antwort, die danach eintrifft, erreicht niemanden, und der Aufruf scheitert mit AskTimeoutError, wenn sein eigenes timeoutMs abläuft. Bei shards() gilt das auch für die Teilantwort des Koordinators, die nach 0,6 × timeoutMs kommt, wenn eine Region langsam ist. Wer länger als eine Minute warten will, erhöht den Query-Timeout des Typs statt des Arguments; die Lebensdauer steigt mit.

const shard = await cluster.sharding.shardRefFor<CounterCommand>('counter', 7);

Hat Shard 7 noch kein Zuhause, platziert dieser Aufruf ihn — genau das, was eine erste Nachricht an ihn auch getan hätte — und antwortet, sobald der Koordinator entschieden hat.

Eine ID, die kein Shard des Typs sein kann — alles außer einer ganzen Zahl von 0 bis numShards - 1 —, wird sofort mit einem RangeError abgelehnt, der den Bereich nennt. Kein Koordinator würde sie je platzieren; Warten endete nur in einem Timeout, der nichts über den Grund sagt.

Ein Shard, der leer passiviert wurde, braucht keine Sonderbehandlung: die Ref bleibt über die Lücke hinweg gültig, und der Shard wird neu erstellt, sobald etwas für ihn eintrifft. Lokal passiert das schon beim Fragen, denn ein Handle auf einen nicht laufenden Actor wäre ein Handle auf nichts; bei einem Shard auf einem anderen Node stellt die Ref über dessen Region zu, die den Shard vor dem Weiterleiten materialisiert. shardRefFor() weckt einen lokalen Shard also sofort, einen entfernten das erste tell. Die Ausnahmen sind ein lokaler Shard, der nach einem Ausfall zurückwartet, und einer, der gerade stoppt, weil er übergeben oder passiviert wird: Dann leitet die Ref über die Region weiter, die festhält, was eintrifft, bis der Shard es annehmen kann, oder es dorthin schickt, wohin ein Handoff den Shard verlegt hat.

Die Ref ist das echte Ding. Ein Shard ist ein Actor (/system/cluster/sharding/region-counter/shard-7), und die Ref trägt diesen Pfad als Identität, egal von welchem Node du gefragt hast — was sich unterscheidet, ist der Weg: direkt zum Actor, wenn dieser Node ihn hostet, über die besitzende Region, wenn nicht. tell funktioniert damit von überall:

// Bring an entity up without sending it a message.
shard.tell({ kind: 'sharding.StartEntity', entityId: 'user-42' });
// Address one entity through the shard.
shard.tell({
kind: 'sharding.EntityEnvelope',
entityId: 'user-42',
message: { id: 'user-42', kind: 'increment' },
});

Und um zu fragen, was ein Shard hält:

const stats = await shard.ask<ShardStats>({ kind: 'sharding.GetShardStats' });
// { shardId: 7, entityCount: 2, entityIds: ['user-42', 'user-99'] }

StartEntity und GetShardStats sind Shard-Nachrichten: der Region statt einer Shard-Ref geschickt, werden sie nicht weitergeleitet, sondern abgelehnt — als Dead Letter, der die Region nennt, gezählt in actor_unhandled_total{class="ShardRegion"}.

entityRefFor ist das Gegenstück zur Region-Ref — ein Handle auf eine einzelne Entity, wo immer sie gerade liegt:

const entity = cluster.sharding.entityRefFor<CounterCommand>('counter', 'user-42');
entity.tell({ kind: 'increment', by: 1 });
const value = await entity.ask<number>({ kind: 'get' });

Zwei Dinge sind anders als beim Reden mit der Region:

  • Die Nachricht trägt ihren Routing-Key nicht mehr selbst. An eine Region zu senden heißt, dass extractEntityId die ID wieder aus deiner Nachricht herausgraben muss — jeder Nachrichtentyp braucht also eine. Der Handle benennt seine Entity direkt, extractEntityId wird nie befragt.
  • Er ist synchron zu bekommen. Der Shard ist hash(entityId) % numShards, es muss also nichts nachgeschlagen werden. Eine Nachricht für einen Shard, dessen Zuhause noch unbekannt ist, puffert die Region — genau wie bisher.

Location-transparent ist er, weil er über die lokale Region routet, und die weiß bereits, wie sie jeden Node erreicht. Eine Proxy-Region (startProxy) reicht aus, um einen auszugeben — der Node muss selbst nichts hosten.

ask funktioniert auf einer Entity-Ref unabhängig davon, wo die Entity liegt: die Region reicht deinen Sender an die Entity durch, die Antwort kommt also direkt zu dir zurück.

Für die Push-Seite abonnierst du ShardMapChanged:

import { match, P } from 'ts-pattern';
import { ShardMapChanged } from 'actor-ts/cluster';
cluster.subscribe((event) =>
match(event)
.with(P.instanceOf(ShardMapChanged), (e) => onShardMapChanged(e))
.otherwise(() => onOtherEvent()));
function onShardMapChanged(event: ShardMapChanged): void {
// event.type — the sharded type name
// event.shards — ReadonlyMap<shardId, regionKey>
// event.regions — the region table, with per-region shard counts
// event.version — increments once per broadcast
}

Das Event feuert auf jedem Node, nicht nur auf dem Leader: der Koordinator broadcastet an jede Region, und die Region publiziert lokal. Genau das macht es für einen Anwendungs-Listener oder ein Per-Node-Dashboard überhaupt brauchbar.

Broadcasts werden zusammengefasst. Allokationsänderungen kommen einzeln pro Shard, und ein frischer Cluster platziert alle Shards auf einmal — version zählt deshalb Broadcasts, nicht einzelne Zuweisungen. Lies sie nicht als “wie viele Shards sind umgezogen”.

Weil das Event jeden Node erreicht, kann ClusterSharding sich einfach das letzte merken — genau das gibt shardMap(typeName) als reines JSON zurück:

const map = cluster.sharding.shardMap('cart');
if (map !== null) {
// map.regions — one entry per region, with its shard ids
// map.shardHome — [{ shard, regionKey }], one per placed shard
// map.version — the coordinator's broadcast counter
// map.leader, map.takenAt — who published it, and when it arrived here
}

Synchron und kostenlos: kein Round-Trip, kein DistributedData, kein coordinatorStateStore. Es ist das, was der Endpunkt GET /cluster/shards serialisiert.

Der Rückgabewert ist null, bis der Koordinator einmal für den Typ publiziert hat — das schließt jeden Node ein, der weder Region noch Proxy dafür gestartet hat, denn der Koordinator broadcastet nur an registrierte Regionen. Und shardHome bleibt leer, bis wirklich ein Shard platziert ist, während sich regions schon bei der Registrierung füllt: lies regions für “wer nimmt teil”, shardHome für “was ist platziert”.

Greif stattdessen zu shards(), wenn du Entity-Zahlen oder lebende Refs brauchst, und zu ShardMapChanged, wenn du die Änderungen statt des letzten Stands willst.

Eine Region registriert sich beim Coordinator, der auf dem Leader läuft — über einen eigenen Retry-Timer. Das ist ein anderer Schritt als der Cluster-Beitritt, und Membership-Konvergenz ist kein Ersatz dafür: ein vollständig konvergierter Cluster kann sehr wohl eine Region halten, die sich noch nicht registriert hat.

if (cluster.sharding.isRegistered('cart')) { /* der Coordinator hat die Region dieser Node bestätigt */ }

Synchron und gratis, wie shardMap, und auf demselben Weg gespeist — aus einem ShardRegionRegistered-Event, das die Region dieser Node publisht, sobald der Coordinator sie bestätigt. false für einen Typ, den diese Node nie gestartet hat; für einen, dessen Registrierung wegen eines numShards-Mismatch abgelehnt wurde; für einen, dessen Region mitgeteilt bekam, dass sie wegen Verstummens entfernt wurde, bis ihre neue Registrierung bestätigt ist; und für einen, dessen Region gestoppt wurde. In jedem dieser Fälle platziert der Coordinator keinen Shard des Typs auf dieser Node — eine Readiness-Probe, die auf diesem Signal aufbaut, nimmt die Node also aus der Rotation, statt sie als bereit zu melden.

Es ist die Sicht dieser Node auf ihre Registrierung, gebaut aus dem, was ihrer Region mitgeteilt wurde, und zwei Situationen sollte man genau kennen:

  • Ein Leader-Wechsel macht es nicht false. Jede Region registriert sich beim Coordinator des neuen Leaders erneut, und die Node gilt währenddessen weiter als registriert — eine Wahl nimmt also nicht alle Nodes gleichzeitig aus der Rotation. Das gilt auch dann, wenn der neue Leader für den Typ gar keinen Coordinator betreibt: Der Wert kann das nicht von einer Neuregistrierung unterscheiden, die noch unterwegs ist. Eine Ablehnung des alten Leaders verfällt mit ihm — vom Leader-Wechsel an, bis der neue Coordinator antwortet, ist registrationRefusal null und der Typ gilt als nicht registriert: wartend, nicht abgelehnt.
  • Von einer Entfernung erfährt die Region durch die Mitteilung des Coordinators, einen einzelnen, unbestätigten Frame. Geht er verloren, behält die Region ihre Shards, und der Wert bleibt true, während der Coordinator keinen Eintrag für die Region mehr hält — bis ihr nächster Beat den Coordinator erreicht, der einen Beat von einer Region, die er nicht kennt, mit der Aufforderung beantwortet, sich zu registrieren. Das Fenster ist ein heartbeat-interval plus ein Round-Trip, und die erneute Registrierung nimmt die veralteten Kopien der umverteilten Shards auf der Region herunter. Ohne Stale-Region-Erkennung wird nichts entfernt, ein solches Fenster gibt es dann nicht.

Diese Probe liefert das Framework mit. Nenne den Typ, und Cluster.join installiert für ihn einen Readiness-Check shard-region:cart, dessen detail sagt, welcher dieser Fälle ihn rot hält:

actor-ts.sharding.healthcheck.names = ["cart"]

Für einen Typ, den nur der Code kennt, registrierst du shardRegionRegistered(cluster, 'cart') aus actor-ts/management selbst — siehe Auf eine Shard-Region warten.

cluster.subscribe((event) => {
if (event instanceof ShardRegionRegistered) console.log(event.type, 'can route');
});

Das Event ist node-lokal wie jedes Cluster-Event: es sagt etwas über die Region dieser Node. Wer die Registrierungen aller Nodes an einer Stelle sehen will, bridgt es — es entsteht auf genau einer Node, ist also ein sinnvoller Bridge-Kandidat:

cluster.eventStream.bridge(ShardRegionRegistered);

Ein Coordinator lehnt eine Region ab, deren numShards nicht zu der Zahl passt, mit der er den Typ verwaltet. Das ist die Signatur eines Rolling Deployments, das die Einstellung auf einem Teil der Nodes geändert hat und auf dem Rest nicht — und es ist der eine Sharding-Fehler, der schlimmer wird, je länger er unbemerkt bleibt: die abgelehnte Region läuft weiter, nimmt weiter Traffic für den Typ an, und alles Angenommene puffert. Am Ende steht eine Node ohne Speicher.

const refusal = cluster.sharding.registrationRefusal('cart');
if (refusal) {
console.error(
`refused: this node has ${refusal.regionNumShards},`
+ ` the coordinator governs ${refusal.coordinatorNumShards}`,
);
}

null, wenn es keine Ablehnung gibt, und geleert, sobald eine spätere Registrierung angenommen wird — ein Deployment, das den Mismatch behebt, meldet also keinen mehr — und wenn der Leader wechselt: Eine Ablehnung ist das Urteil des Coordinators, der sie ausgesprochen hat, und bis der Coordinator des neuen Leaders antwortet, gibt es keine zu melden. Dieselbe Ablehnung wird als Cluster-Event ShardRegionRegistrationRefused publisht, für Code, der reagieren statt pollen will.

Alarmieren sollte man auf den Zähler, der ohne eigenen Code auskommt:

cluster_sharding_registrations_refused_total{type="cart",reason="num-shards-mismatch"}

Jeder Wert ungleich null ist einen Alarm wert — eine Ablehnung ist nie vorübergehend und löst sich nie von selbst. Sie folgt dem Label-Schema von cluster_gossip_records_refused_total und wird, wie jede Metrik hier, nur erfasst, wenn Metriken auf dem System aktiviert sind.

  • Sharding — Überblick — die Region-, Shard- und Entity-Actors, auf die diese APIs dir Refs geben.
  • Rebalance — warum Platzierung sich bewegt und was dabei mit einer Shard-Ref passiert.
  • HTTP-Management-Endpunkte — GET /cluster/shards, die serialisierbare Sicht auf dieselbe Karte.