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.
Die Shards auflisten
Abschnitt betitelt „Die Shards auflisten“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.
Was es kostet
Abschnitt betitelt „Was es kostet“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.
Wie lange eine Abfrage wartet
Abschnitt betitelt „Wie lange eine Abfrage wartet“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.
Eine Ref auf einen Shard
Abschnitt betitelt „Eine Ref auf einen Shard“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"}.
Eine Ref auf eine Entity
Abschnitt betitelt „Eine Ref auf eine Entity“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
extractEntityIddie ID wieder aus deiner Nachricht herausgraben muss — jeder Nachrichtentyp braucht also eine. Der Handle benennt seine Entity direkt,extractEntityIdwird 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.
Der Karte folgen
Abschnitt betitelt „Der Karte folgen“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”.
Die letzte Karte, ohne Abfrage
Abschnitt betitelt „Die letzte Karte, ohne Abfrage“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.
Kann die Region schon routen?
Abschnitt betitelt „Kann die Region schon routen?“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, istregistrationRefusalnullund 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 einheartbeat-intervalplus 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);Wenn der Coordinator eine Region ablehnt
Abschnitt betitelt „Wenn der Coordinator eine Region ablehnt“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.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- 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.
