Sharding — Überblick
Cluster-Sharding ist die Antwort des Frameworks auf “ich habe ein paar Millionen Entities, jede braucht ihren eigenen Actor, verteilt über N Nodes.” Beispiele: Per-User-Sessions, Per-IoT-Device-Controller, Per-Order-Koordinatoren, Per-Game-Room-Actors.
Der Nutzer gibt dem Framework eine Möglichkeit, eine Entity-ID aus jeder Nachricht zu extrahieren; das Framework hasht die ID auf einen Shard; der Koordinator entscheidet, welcher Node diesen Shard hostet; die lokale Region des Nodes routet an diesen Shard, der den Entity-Actor bei Bedarf spawnt. Wenn Nodes kommen und gehen, rebalanciert der Koordinator die Shards über die neue Topologie.
Jede Entity ist ein Actor, auf einem Node, zu einer Zeit — genauso wie ein Singleton, aber skaliert auf N Entities. Failover passiert automatisch: wenn ein Node geht, wandern seine Shards woandershin und die Entities werden dort neu gespawnt.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“import { match } from 'ts-pattern';import { Actor } from 'actor-ts';import { Cluster, ClusterBootstrapOptions, StartShardingOptions } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };type ViewCommand = { entityId: string; kind: 'view'; replyTo: ActorRef<Cart> };type CartCommand = AddCommand | ViewCommand;
class CartActor extends Actor<CartCommand> { private items: string[] = [];
override onReceive(command: CartCommand): void { match(command) .with({ kind: 'add' }, (c) => this.onAdd(c)) .with({ kind: 'view' }, (c) => this.onView(c)) .exhaustive(); }
private onAdd(command: AddCommand): void { this.items.push(command.sku); } private onView(command: ViewCommand): void { command.replyTo.tell({ items: this.items }); }}
// Setup — einzeiliger Cluster- + Sharding-Einstieg:const { system, cluster } = await Cluster.bootstrap(ClusterBootstrapOptions.create('my-app'));
const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((message) => message.entityId);const cartRegion = cluster.sharding.start('cart', CartActor, startShardingOptions);
// Verwendung — `tell` an die Region, mit Entity-ID in der Nachricht:cartRegion.tell({ entityId: 'user-42', kind: 'add', sku: 'book-1' });cartRegion.tell({ entityId: 'user-42', kind: 'view', replyTo: ... });// ^^^^^^^^^^// Gleiche ID → gleicher Entity-Actor, jedes Mal, unabhängig vom Node.cluster.sharding.start() akzeptiert mehrere Aufruf-Formen — nimm die,
die zur Entity passt. Die kürzeste lässt die Entity ihre eigene
Identität deklarieren, wodurch weder Type-Name noch Entity-ID-Extractor
am Aufrufort wiederholt werden:
class CartActor extends Actor<CartCommand> { static readonly shard = ShardKey.of<CartCommand>('cart', (command) => command.entityId); // ...}
const cartRegion = cluster.sharding.start(CartActor);const cart = cluster.sharding.entityRefFor(CartActor, 'user-42');Die Identität eines ShardKey ist allein sein typeName; der
Extractor reitet mit, damit die deklarierende Klasse die einzige
Wahrheitsquelle ist — ein Node, der Entities nur nachschlägt, kann
denselben Typ mit ShardKey.of<CartCommand>('cart') ohne Extractor
benennen. Ein extractEntityId in den Options überschreibt den auf
dem Key.
Die übrigen Formen bleiben unverändert:
// 1. Klassen-Kurzform:const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);cluster.sharding.start('cart', CartActor, startShardingOptions);
// 2. Factory-Kurzform — wenn die Entity Konstruktor-Argumente braucht:const startSharding2Options = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);cluster.sharding.start('cart', () => new CartActor(deps), startSharding2Options);
// 3. Vollform — alle Settings über den Builder:const startSharding3Options = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((m) => m.entityId) .withNumShards(16) .withRole('cart-host');cluster.sharding.start( startSharding3Options,);cluster.sharding ist eine memoisierte Fassade — wiederholte
Zugriffe liefern dieselbe ClusterSharding-Instanz. Die explizite
Form ClusterSharding.get(system, cluster) funktioniert weiter und
liefert dasselbe Objekt; greif dazu nur, wenn Du die Klasse
außerhalb eines Cluster-Handles brauchst.
Aus Sicht des Aufrufers ist die cartRegion ein einzelner
ActorRef. Hinter den Kulissen:
- Die Region berechnet aus
entityIdeinen Shard (Default: Hash auf einen von 64 Shards). - Sie fragt den Koordinator “wem gehört dieser Shard?”
- Wenn der Besitzer dieser Node ist, spawnt sie die Entity (falls noch nicht vorhanden) und leitet die Nachricht weiter.
- Wenn der Besitzer ein anderer Node ist, leitet sie über den Cluster-Transport an dessen Region, die dasselbe macht.
Die vier Actors im Spiel
Abschnitt betitelt „Die vier Actors im Spiel“| Actor | Rolle |
|---|---|
| Region | Eine pro Node. Routet Nachrichten an den Besitzer des richtigen Shards und entscheidet, wann lokale Entities — und leer gewordene Shards — passiviert werden. |
| Shard | Einer pro hier gehostetem Shard, Kind der Region. Besitzt die Entity-Actors: spawnt sie, stoppt sie, puffert für eine, die gerade geht. Verschwindet selbst, sobald er sein Fenster lang leer stand, und kommt mit der nächsten Nachricht zurück. |
| Koordinator | Einer pro Cluster (Singleton, auf dem Leader). Entscheidet, welcher Node welchen Shard besitzt. Behandelt Rebalancing bei Mitgliedschaftsänderungen und beim Herunterfahren einer Region. |
| Entity | Eine pro entityId. Kind ihres Shards, auf dem Node, dem aktuell der Shard gehört, in den die ID hasht. |
Damit haben Entities einen echten Pfad —
/system/cluster/sharding/region-counter/shard-7/entity-user-42 — und genau das macht
einen Shard überhaupt adressierbar. Siehe
Introspektion zum Auflisten von
Shards und zum Holen von Refs darauf.
Die Region ist das Thema dieser Seite; die Entscheidungen des Koordinators haben eigene Seiten — siehe die Allokationsstrategie und Rebalance für die Mechanik.
Wissen, welche Entity man ist
Abschnitt betitelt „Wissen, welche Entity man ist“Eine Entity braucht fast immer die ID, über die sie geroutet wurde — für den Namen ihres Journal-Streams, ihres Pub/Sub-Topics oder einer Zeile in einer fremden Datenbank. Sie liest sie an sich selbst ab:
class CartEntity extends Actor<CartCommand> { override preStart(): void { this.log.info(`cart ${this.entityId} woke up in shard ${this.entity.shardId}`); }}this.entityId | Der Wert, den extractEntityId zurückgegeben hat — unverändert. |
this.entity | Dieselbe ID plus typeName und shardId. |
this.context.entity | Die Option-Form — None, wenn dieser Actor keine Entity ist. Die beiden Getter darüber werfen stattdessen. |
Der häufigste Fall ist eine persistenceId pro Entity — genau das gibt
einem geshardeten PersistentActor
einen Event-Stream pro Entity statt einen pro Typ:
class CartEntity extends PersistentActor<CartCommand, CartEvent, CartState> { override get persistenceId(): string { return `cart-${this.entityId}`; }}Die Identität sitzt auf der Entity und sonst nirgends — die eigenen
Kinder einer Entity bekommen None, this.context.entity.nonEmpty
beantwortet also „bin ich die Entity?“. Ein Kind, das die ID braucht,
bekommt sie explizit weitergereicht.
Um eine Entity isoliert zu testen, gibst du ihr die Identität direkt, statt einen Cluster darum herum hochzufahren:
import { ActorOptions } from 'actor-ts';
const cartOptions = ActorOptions.create() .withEntity({ entityId: 'user-42', typeName: 'cart', shardId: 3 });const cart = system.spawn(CartEntity, 'cart-under-test', cartOptions);Warum nicht einfach den Pfad auslesen?
Abschnitt betitelt „Warum nicht einfach den Pfad auslesen?“.../shard-7/entity-user-42 sieht aus, als trüge er die ID, und für
einfache IDs funktioniert das Abschneiden des entity--Präfixes auch.
Es ist aber nicht die ID: Actor-Namen haben ein eingeschränktes
Alphabet, deshalb maskiert der Shard beim Benennen des Kindes alles, was
ein Name nicht tragen kann — eine Code-Unit außerhalb von
[A-Za-z0-9_-.@:+] wird zu ~ plus vier Hex-Ziffern, user/42 heißt
also entity-user~002F42.
Die Maskierung ist injektiv: zwei verschiedene IDs landen nie auf einem Namen. Das ist eine Korrektheitseigenschaft, keine Feinheit — ein geteilter Name bedeutet, dass die zweite Entity unter einem schon vergebenen Namen startet, und der resultierende Fehler reißt den Shard mitsamt allen anderen Entities darin mit.
Was sie nicht ist: eine zweite Schreibweise der ID. Nichts dekodiert
ein Pfadsegment, bewusst, und die Maskierung ist kein Teil der API. Der
Pfad ist ein Etikett; entityId ist der Wert.
Konfiguration
Abschnitt betitelt „Konfiguration“ShardingOptionsType<TMessage> — die Felder, die du am häufigsten anfasst:
type ShardingOptionsType<TMessage> = { typeName: string; entityActor: ActorClassOrFactory<TMessage>; entityOptions?: ActorOptions<TMessage>; extractEntityId: (message: TMessage) => string; extractEntityMessage?: (message: TMessage) => unknown; numShards?: number; // Default 64 role?: string; // auf Nodes mit dieser Rolle beschränken proxy?: boolean; // nur Routing, keine lokalen Entities rememberEntities?: boolean; // Entities bei Failover neu spawnen (#) passivationIdleMs?: number; // idle Entities auto-stoppen, Default 5 min shardPassivationIdleMs?: number; // leere Shards auto-stoppen, folgt obigem maxEntities?: number; // Cap für residente Entities, pro Typ pro Node passivationReplacement?: EntityReplacementPolicy; // welche Entity das Cap hergibt};| Feld | Was es steuert |
|---|---|
typeName | Ein String, der diesen sharded Typ identifiziert. Verschiedene Typen können im selben Cluster koexistieren (cart, session, order). |
extractEntityId(message) | Zieh die Entity-ID aus einer Nachricht. Das ist der Key, der zu einem Shard gehasht wird. |
extractEntityMessage(message) | (Optional) Wenn der Nachrichten-Envelope Routing-Info plus eine Payload enthält, entfernt das den Envelope, bevor die Entity ihn sieht. Default ist die Nachricht unverändert. |
numShards | In wie viele Shards der Entity-Raum aufgeteilt wird. 64 reichen für die meisten Cluster; setze auf 1000 für sehr große Cluster (>50 Nodes). Muss auf jedem Node identisch sein, der diesen Typ startet oder proxyt — siehe unten. |
role | Nur Mitglieder mit dieser Rolle hosten Shards dieses Typs. Nützlich, um compute-schwere Entities auf dedizierten Nodes zu platzieren. Auch node-weit setzbar als actor-ts.sharding.role — siehe Platzierung aus der Config-Datei. |
proxy | Dieser Node leitet Nachrichten an die Region weiter, hostet aber nie lokale Entities. Wird für Client-Nodes in einem asymmetrischen Cluster verwendet. |
rememberEntities | Persistiere die Menge der aktiven Entity-IDs. Nach einem Koordinator-Failover (oder vollem Cluster-Neustart) werden diese IDs eager gespawnt, sodass Nachrichten nicht die gesamte Flotte neu erstellen müssen. |
passivationIdleMs | Stoppt eine Entity nach so viel Leerlaufzeit. Befreit Speicher; die nächste Nachricht für dieselbe ID erstellt die Entity neu. Default sind 5 Minuten; 0 schaltet es ab. |
shardPassivationIdleMs | Stoppt einen Shard, nachdem er so lange leer stand. Ungesetzt folgt er passivationIdleMs; 0 hält leere Shards resident, während Entities weiterhin passivieren. |
maxEntities | Wie viele Entities dieses Typs auf diesem Node resident sein dürfen. Wird das überschritten, wird eine passiviert, um Platz zu machen. 0 (Default) heißt kein Cap. Nicht node-weit: zwei gestartete Typen bekommen je die volle Zahl. |
passivationReplacement | Welche residente Entity das Cap hergibt — 'least-recently-used' (Default), 'segmented-least-recently-used' oder 'least-frequently-used'. Bei maxEntities 0 wirkungslos; siehe Wählen, was ein voller Node hergibt. |
Die Defaults sind sinnvoll für kleine Cluster. Für Produktion
willst du meistens rememberEntities: true und ein
passivationIdleMs passend zu deinem Verkehrsmuster.
Platzierung aus der Config-Datei
Abschnitt betitelt „Platzierung aus der Config-Datei“role ist die einzige Platzierungsoption mit einem HOCON-Key, denn welche
Rolle einen Typ hostet, ist über ein Deployment hinweg einheitlich:
actor-ts.sharding.role = "backend"Der Key gilt für jeden auf dem Node gestarteten Sharded Type ohne eigenes
withRole, und ein explizites withRole sticht ihn weiterhin — die übliche
Reihenfolge explizite Optionen > HOCON > Built-in-Defaults, pro Feld.
Was er nicht tut: einem Node die Rolle geben. Die eigenen Rollen eines Nodes
sind eine eigene Einstellung, und zwar eine pro Node, während sharding.role
überall gleich ist: ClusterOptions.withRoles im Code oder
actor-ts.cluster.roles in
der Config des Nodes, meist aus seiner Umgebung befüllt:
actor-ts.cluster.roles = [ ${?NODE_ROLE} ]const clusterOptions = ClusterOptions.create() .withHost('10.0.0.7') .withPort(2551) .withRoles(['backend']);Setzt du nur sharding.role und kein Mitglied passt dazu, findet der
Koordinator keinen Kandidaten, es wird nie etwas zugeteilt, und jede Nachricht
für den Typ staut sich im Routing-Puffer der Region. Still ist das nicht — der
Koordinator warnt einmal mit der Rolle, der Zahl der ausgeschlossenen
registrierten Regionen und beiden Stellen, an denen ein Node seine Rollen
deklariert — aber es ist eine Warnung und kein Startfehler, also lies sie.
proxy hat bewusst keinen Key: Es ist Topologie pro Node, ein zweites start
mit abweichendem Wert wirft, und ein von allen Nodes geteiltes proxy = on
ließe niemanden mehr etwas hosten.
numShards ist eine clusterweite Vereinbarung
Abschnitt betitelt „numShards ist eine clusterweite Vereinbarung“Eine Shard-ID ist hash(entityId) % numShards, und jeder Node
berechnet sie für sich. Zwei Nodes mit unterschiedlichen Werten legen
dieselbe Entity-ID also in unterschiedliche Shards, jeder besitzt am
Ende den Shard, den seine eigene Rechnung ergeben hat, und beide
betreiben eine lebende Instanz der Entity — unter
shard-6/entity-user-7 und shard-50/entity-user-7, Pfaden, die
niemals kollidieren. Bei einer persistenten Entity heißt das zwei
Schreiber auf einer persistenceId.
Deshalb reist der Wert in der Registrierung der Region mit, und der Koordinator verweigert eine Region, die nicht übereinstimmt:
ERROR [sharding] the coordinator refused to register region 'counter':numShards must match across the cluster, but this node is configuredwith 32 and the coordinator governs the type with 64.Eine verweigerte Region bleibt oben und puffert weiter — sie bekommt nie einen Shard zugewiesen, die Fehlkonfiguration ist also ein Stillstand mit einem Fehler daneben statt eines stillen Splits. Korrigiere den Wert und starte den Node neu.
Eine Region, die vorher schon Shards gehostet hat, gibt sie auf der
Stelle ab. Dieser Fall ist nicht exotisch: Genau ihn erzeugt ein
Rolling Deploy in dem Moment, in dem die Leader-Rolle einen bereits
aktualisierten Node erreicht. Die Region wurde vom vorherigen Leader
akzeptiert, hält also echte Shards und echte Entities, und der neue
Koordinator verweigert sie. Sie stoppt jeden dieser Shards — ein
richtiger Stopp, damit die Entities darunter ihr postStop durchlaufen
und eine persistente flusht — und gibt im selben Schritt den Besitz ab.
Das macht aus der Verweigerung einen Stillstand auf diesem Node statt
einer Hälfte eines Splits. Zurück kommt nichts, bevor die Werte
übereinstimmen; der gepufferte Verkehr wartet.
Das ist naturgemäß asynchron: Eine Region registriert sich, nachdem
start(...) zurückgekehrt ist, versucht es erneut, bis der Koordinator
antwortet, und registriert sich bei jedem Leader-Wechsel neu. Es gibt
keinen Aufruf, aus dem geworfen werden könnte — deshalb kommt das
Urteil als Log-Zeile und nicht als Exception.
Zwei Konsequenzen, die man kennen sollte:
- Ein Proxy-Node zählt mit.
startProxyhasht genau wie eine hostende Region und braucht deshalb dasselbenumShards; wer einen aus einem bloßen Key in einem Cluster startet, der nicht den Default verwendet, bekommt ihn verweigert. actor-ts.sharding.number-of-shardsin einer von allen Nodes geteilten Konfigurationsdatei zu setzen ist der fehlerärmste Weg, sie im Gleichschritt zu halten.
Die Verweigerung übersteht auch einen
coordinatorStateStore. Dieser
Store erlaubt einem neuen Leader, den Reallokations-Sturm zu
überspringen, indem er die Allokationskarte seines Vorgängers übernimmt,
und jede Shard-ID in so einem Snapshot entstand unter dem Wert des
schreibenden Koordinators — deshalb trägt ein Snapshot diesen Wert
jetzt als Stempel, und einer, der unter einem anderen (oder, bei einem
vor dem Stempel geschriebenen Snapshot, unter einem ungenannten) Wert
entstand, wird als Ganzes verworfen, mit einem WARN, das beide Zahlen
nennt. Eine Region, die der Koordinator bereits verweigert hat, wird
übersprungen, auch wenn der Snapshot sie nennt. Ohne diese beiden
Prüfungen setzte der Ladepfad die verweigerten Regionen direkt zurück in
den Platzierungs-Pool: Ein Rolling Deploy, der den Wert ändert, hätte das
Split-Routing über den Snapshot wiederhergestellt statt über den
Registrierungs-Handshake — die einzige Stelle, an der die Werte
verglichen werden.
Einen Snapshot zu verwerfen kostet einen Reallokationsdurchlauf, also genau das, was jeder Cluster ohne Store bei einem Leader-Wechsel schon immer tut — und die nächste Allokationsänderung unter dem neuen Leader schreibt einen gestempelten Snapshot, es passiert also einmal.
Denselben Typ auf einem Node zweimal zu starten — start() nach
startProxy() oder umgekehrt — wirft. Der zweite Aufruf gab bisher die
Region des ersten zurück, sodass ein Node, der eine hostende Region
wollte, den Proxy bekam — dessen Platzhalter-Entity-Factory wirft, sobald
lokal ein Shard landet.
Fünf davon sind auch HOCON-Keys — number-of-shards,
remember-entities, passivation-idle, shard-passivation-idle und
max-entities — ebenso die Koordinator-Keys rebalance-interval und
hand-off-timeout sowie der ganze passivation-Unterblock, der
entscheidet, welche Entity das Cap hergibt. Sie setzen die node-weite
Grundeinstellung für jeden sharded Typ und liegen unter dem, was
start(...) explizit übergibt — ein Per-Typ-Wert im Builder gewinnt also
weiterhin. Siehe
Konfiguration.
actor-ts.sharding { number-of-shards = 128 passivation-idle = 2 minutes max-entities = 50000 passivation.replacement = segmented-least-recently-used}Passivierung
Abschnitt betitelt „Passivierung“Passivierung stoppt eine idle Entity, um Speicher freizugeben; die nächste Nachricht für dieselbe ID erstellt sie neu. Wie auch immer sie ausgelöst wird — die Region puffert Nachrichten, die eintreffen, während die Entity stoppt, und spielt sie an die frische Inkarnation zurück, sodass nichts verloren geht.
Das Standard-Idle-Fenster beträgt 5 Minuten. Setze
passivationIdleMs — im Code oder über
actor-ts.sharding.passivation-idle —, um es zu ändern, oder 0, um es
abzuschalten und jede Entity für die Lebensdauer ihres Nodes resident zu
halten.
Automatisch — wenn passivationIdleMs ohne Verkehr abläuft oder
maxEntities überschritten wird (verdrängt wird die Entity, die die
Ersetzungsstrategie benennt), wird die Entity gestoppt. Es wird nichts an
die Entity geschickt, und es gibt keine Quittung. Die Entscheidung
trifft die Region, weil nur sie den Verkehr über alle Shards dieses Nodes
sieht — deshalb ist maxEntities eine Obergrenze pro Typ pro Node, nicht
pro Shard — und der Shard, dem die Entity gehört, führt sie aus.
Manuell (graceful) — eine Entity bittet darum, passiviert zu
werden, indem sie ein Passivate an ihren Parent schickt, also an ihren
Shard. Passivate trägt eine Stop-Nachricht, die an die Entity
zurückgeleitet wird, sodass die Entity genau entscheidet, wann und wie
sie herunterfährt (laufende Arbeit abschließen, State flushen, dann
terminieren). PoisonPill als Stop-Nachricht terminiert die Entity,
sobald sie zurückkommt:
import { match } from 'ts-pattern';import { PoisonPill, Actor } from 'actor-ts';import { Passivate } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };type CheckoutCommand = { entityId: string; kind: 'checkout' };type CartCommand = AddCommand | CheckoutCommand;
class CartActor extends Actor<CartCommand> { private items: string[] = [];
override onReceive(command: CartCommand): void { match(command) .with({ kind: 'add' }, (c) => this.onAdd(c)) .with({ kind: 'checkout' }, () => this.onCheckout()) .exhaustive(); }
private onAdd(command: AddCommand): void { this.items.push(command.sku); }
// Mit dem Warenkorb fertig — die Region bitten, uns zu passivieren. private onCheckout(): void { this.context.parent.forEach((parent) => parent.tell(new Passivate(PoisonPill.instance, this.self), this.self)); }}Die Stop-Nachricht ist eine Bitte: die Entity entscheidet, wann sie darauf
reagiert. Tut sie es nie, terminiert sie nie — und ihr Platz bleibt für die
Lebensdauer des Nodes gegen maxEntities belegt. passivationStopTimeoutMs
(actor-ts.sharding.passivation.stop-timeout) ist die Rückfallebene dafür:
danach stoppt der Shard die Entity hart, genau so, wie es eine von der Region
getriebene Passivierung tut.
Sie ist standardmäßig aus (0, unbegrenztes Warten), und zwar weil der
kooperative Vertrag der Punkt ist. Eine Entity mitten im Leeren — ein langer
Flush, ein langsamer letzter Write — darf so lange brauchen, wie das Leeren
dauert, und ein harter Stopp bricht diesen Flush ab; nur du weißt, wie lange
deiner legitim laufen darf. Setze sie dort, wo eine Entity, die nie auf die
Nachricht reagiert, ein Fehler wäre, den es einzudämmen gilt. Sie ist von
maxEntities unabhängig: ein positiver Wert schärft sie mit oder ohne Cap.
Wählen, was ein voller Node hergibt
Abschnitt betitelt „Wählen, was ein voller Node hergibt“maxEntities sagt, wie viele Entities resident bleiben;
passivationReplacement sagt, welche geht, wenn eine neue dazukommt. Jeder
Regler hier ist wirkungslos, solange maxEntities 0 ist — der Default.
Die Default-Strategie 'least-recently-used' hat einen blinden Fleck:
Aktualität kann einmal überhaupt benutzt nicht von bis eben ständig benutzt
unterscheiden. Ein Durchlauf über einen großen kalten Schlüsselraum — ein
nächtlicher Export, ein Crawler, ein Backfill — verdrängt dein Arbeitsset also
Entity für Entity und hinterlässt einen Node voller IDs, nach denen nie wieder
jemand fragt. Zwei Optionen beheben das, und sie greifen ineinander:
const shardingOptions = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((command) => command.entityId) .withMaxEntities(50_000) // Bewährung für eine einmal gesehene Entity, geschützt für eine erneut // gesehene; verdrängt wird aus der Bewährung, ein Scan kann also nur einen // anderen Scan verdrängen. .withPassivationReplacement('segmented-least-recently-used') .withPassivationSegmentedProtectedProportion(0.8) // Ein kleines Fenster vor der Strategie, damit die bei der Aufnahme // beurteilte Entity nie die ist, auf die eine Nachricht wartet. .withPassivationAdmissionWindowProportion(0.01) // …und was beurteilt: ein kompakter Sketch darüber, wie oft jede ID gesehen // wurde — er erinnert sich auch an IDs, die der Node nicht mehr hält. .withPassivationAdmissionFilter('frequency-sketch');'least-frequently-used' ist die dritte Strategie — die wenigsten Zugriffe
verlieren, wobei die Zähler periodisch halbiert werden, damit die Rangfolge dem
jüngeren Verkehr folgt statt einer Lebenszeitsumme. Sie passt zu einem
Arbeitsset, das stabil, aber nicht aktuell ist, etwa eine Geräteflotte, die in
langsamem Takt meldet.
Der Filter braucht ein Fenster: eine Region kann die Entity, für die gerade
eine Nachricht eingetroffen ist, nicht ablehnen — 'frequency-sketch' mit
passivationAdmissionWindowProportion: 0 wird deshalb bei start(...)
abgelehnt, statt still nichts zu tun. Alle fünf Regler sind zugleich
HOCON-Keys unter
actor-ts.sharding.passivation.
Shards passivieren ebenfalls
Abschnitt betitelt „Shards passivieren ebenfalls“Alle Entities eines Shards zu passivieren ließ früher den Shard selbst
zurück — einen lebenden Actor mit einer leeren Map. Außer einem
Rebalance stoppte ihn nichts, und da Entity-IDs über den Hash-Raum
streuen, wurde auf einem lang laufenden Node irgendwann jeder Shard
einmal angefasst und blieb dann. Bei numShards = 64 sind das 64 idle
Actors ohne Inhalt.
Deshalb wird auch ein Shard gestoppt, der shardPassivationIdleMs lang
leer stand. Die Region behält die Ownership — nur der Actor geht —,
der Shard bleibt also routbar, und die nächste Nachricht für ihn
erstellt Shard und Entity gemeinsam neu, ohne Umweg über den
Koordinator. Ungesetzt folgt das Fenster passivationIdleMs, was
meistens genau richtig ist: ein Shard ist leer, gerade weil seine
Entities idle wurden.
const shardingOptions = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((command) => command.entityId) .withPassivationIdleMs(120_000) // Shards sind billig zu halten und kosten einen Respawn, wenn sie gehen — // auf einem belebten Node ist es ein guter Handel, sie ihre Entities eine // Weile überleben zu lassen. .withShardPassivationIdleMs(600_000);Setze shardPassivationIdleMs: 0, um leere Shards resident zu halten,
während Entities weiterhin passivieren. Region und Koordinator sind in
beiden Fällen unberührt — sie laufen für die Lebensdauer des Nodes.
Gestoppt wird immer nur ein leerer Shard, es steht also kein
Entity-State auf dem Spiel, und Nachrichten, die während des Stoppens
eintreffen, werden genauso gepuffert und nachgespielt wie bei einer
Entity. „Leer“ ist dabei die Antwort des Shards, nicht die Vermutung der
Region: Die Region bittet einen Shard, den sie für leer hält, zu
stoppen, und der Shard stoppt nur, wenn er weiterhin nichts hat — keine
Entity, die die Nachricht direkt vor der Bitte erstellt hat, keine
gemerkte Entity, die ein Recovery-Batch gerade gestartet hat, keine
Entity im Backoff. Sonst bleibt
er, die Region routet wieder zu ihm, und ein späterer Sweep fragt
erneut. Auch eine Shard-Ref bleibt über die Lücke hinweg gültig — siehe
Introspection, wo ShardInfo
zusätzlich ein resident-Flag meldet, das einen passivierten Shard von
einem bloß leeren unterscheidet.
Wenn Shards und Entities immer wieder ausfallen
Abschnitt betitelt „Wenn Shards und Entities immer wieder ausfallen“Eine Entity, die ihre Arbeit nicht tun kann — eine Poison-Nachricht, ein Store, der nicht erreichbar ist, ein Start, der wirft —, fällt jedes Mal erneut aus, wenn sie neu erstellt wird. Drei Wege erstellen sie neu, und sie verhalten sich unterschiedlich:
- Eine Entity in ihrem Shard. Der Shard beaufsichtigt seine
Entities wie jeder Parent: Eine ausgefallene Entity wird an Ort und
Stelle neu gestartet, sofort, bis zu zehnmal pro Minute. Dieses
Budget gehört dem Shard, alle Entities des Shards zehren also vom
selben. Ist es aufgebraucht, wird die Entity gestoppt, und der Shard
erstellt sie erst nach einer Wartezeit neu,
entity-restart-backoff— siehe eine Entity, die immer wieder stoppt. - Ein Shard in seiner Region. Ein Fehler, den der Shard nicht auffängt — eine Entity, deren eigene Strategie eskaliert, oder ein Fehler im Shard selbst —, erreicht die Region, und die stoppt den Shard, statt ihn neu zu starten. Jede Entity unter dem Shard stoppt mit ihm, und die Region vergisst sie.
- Ein Shard, der zurückkommt. Ein Shard, der gestoppt ist, ohne dass
die Region es verlangt hat — also alles außer einer Übergabe, einer
Passivierung oder einer Freigabe —, wird nach einer Wartezeit neu
erstellt,
shard-failure-backoff, nicht bei der nächsten Nachricht. Ist die Wartezeit um, erstellt die Region ihn neu, spielt nach, was auf ihn gewartet hat, und fragt beirememberEntitiesden Koordinator nach den Entities des Shards, sodass sie ganz ohne Verkehr zurückkommen.
Solange der Shard unten ist, behält die Region seine Ownership:
Nichts wird neu vergeben, und der Koordinator platziert den Shard
weiterhin hier. Nachrichten für ihn warten im Region-Puffer gegen
buffer-size — jenseits des Caps geht die neueste mit ihrem Sender an
die Dead Letters — und werden mit ihren Sendern zugestellt, sobald der
Shard zurück ist. Das betrifft, was die Region nach dem Tod des Shards
routet. Was sie schon in einen Shard geroutet hatte, der ausfällt — Fall 2
oben —, und was seine Entity noch nicht erreicht hat, geht mit dem Shard
verloren: Die Region erfährt vom Ausfall erst durch den Tod des Shards,
und was in einem stoppenden Shard oder seinen Entities noch wartet, geht
an die Dead Letters, jede Nachricht mit ihrem Sender. Eine Nachricht an
eine gesunde Entity, die genau dann geschickt wird, wenn der Fehler ihrer
Geschwister-Entity eskaliert, kann also verloren gehen. Der Neustart an
Ort und Stelle, den das Stoppen ersetzt hat, behielt die Mailbox des
Shards, riss aber jede Entity unter dem Shard mit, ohne dass die Region
davon erfuhr. Nichts anderes holt den Shard früher zurück: keine
Nachricht, keine Shard-Ref aus shardRefFor() (die bis dahin über die
Region weiterleitet), keine wiederholte Platzierung und keine erneut
geschickte Registry. Eine Nachricht an eine Shard-Ref, die nicht für
eine Entity ist — etwa GetShardStats —, geht an die Dead Letters.
Jeder Tod in Folge verdoppelt die Wartezeit, von min bis max,
gestreut um random-factor in beide Richtungen; ein Shard, der seit
seiner Rückkehr reset-after lang nicht ausgefallen ist, beginnt beim
nächsten Tod wieder bei min — eine Passivierung dazwischen ist kein
Ausfall, ein kalter Shard, den eine Poison-Nachricht neu erstellt, wird
also danach beurteilt, wie lange er gesund war, nicht nach den wenigen
Millisekunden seiner neuen Inkarnation. Mit
den ausgelieferten Werten ist ein Shard, der ab und zu ausfällt, nach
etwa 200 ms zurück, und einer, der bei jedem Start ausfällt, wird etwa
alle zehn Sekunden neu erstellt statt tausende Male pro Sekunde:
actor-ts.sharding.shard-failure-backoff { min = 200ms # the first wait; must be > 0 max = 10s # the doubling stops here random-factor = 0.2 # each wait spread by up to 20 % either way reset-after = 60s # no failure for this long, and the next death waits min}Der Builder nimmt dieselben vier, in Millisekunden und als Anteil:
const shardingOptions = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((command) => command.entityId) .withRememberEntities(true) // The store behind these entities takes seconds to fail over: wait at // least one, and never more than a minute. .withShardFailureBackoffMinMs(1_000) .withShardFailureBackoffMaxMs(60_000);Was das für die eigene supervisorStrategy einer Entity bedeutet,
gesetzt über entityOptions:
- Ihre Neustarts geschehen sofort und gehen vom Budget des Shards ab. Eine Entity in einer Neustart-Schleife kann das Kontingent aufbrauchen, das ihre Geschwister gebraucht hätten, und nichts bremst sie, bis dieses Budget erschöpft ist; von da an bremst sie der Entity-Restart-Backoff unten.
- Eine Strategie, die eskaliert, übergibt den Fehler dem ganzen Shard. Jedes Geschwister stoppt mit, und alle warten den Backoff des Shards ab. Eskaliere nur bei Fehlern, die bedeuten, dass der Shard selbst nicht weiterkann.
Eine Entity, die immer wieder stoppt
Abschnitt betitelt „Eine Entity, die immer wieder stoppt“Jenseits des Neustart-Budgets wird eine Entity gestoppt, und die nächste
Nachricht für sie hat bisher eine neue erstellt: Eine Entity, die bei
jeder Nachricht ausfiel, wurde pro Nachricht neu erstellt — dreißig
Instanzen für dreißig Nachrichten —, und jede öffnete ihre Recovery
gegen das, woran sie scheiterte. Jetzt hält der Shard sie zuerst eine
Weile unten, entity-restart-backoff, und die Wartezeit wächst, solange
sie immer wieder stoppt.
Ein Shard kann nicht sehen, warum eine Entity gestoppt ist, also
schickt er jeden Stopp, um den er nicht gebeten hat, in den Backoff:
einen Ausfall jenseits des Budgets, einen Start oder eine Recovery, die
immer wieder scheitert, einen Recovery-Fehler, den die Entity verschluckt
hat, ein verlorenes Lease, ein schlichtes stopSelf. Der eine Stopp, um
den er bittet, ist eine Passivierung — das eigene Passivate der
Entity oder die Idle- und Kapazitäts-Passivierung der Region —, und eine
so gestoppte Entity kommt bei der nächsten Nachricht sofort zurück.
Stoppe eine Entity also mit Passivate, wenn du es so meinst, nicht mit
stopSelf.
Die Neustarts innerhalb des Budgets bleiben sofort: Eine
SupervisorStrategy hat keine Verzögerung zu vergeben, und dies ist die
Wartezeit danach. Währenddessen:
- Nachrichten für die Entity werden zurückgehalten, jede mit ihrem
Sender, und in Reihenfolge übergeben, sobald sie zurück ist. Das
Zurückhalten ist pro Shard auf
buffer-sizebegrenzt, über die Entities des Shards zusammen; darüber hinaus geht die neueste mit ihrem Sender an die Dead Letters, mit einer Warnung pro Episode. Ein Shard, der stoppt, während er Nachrichten zurückhält, gibt sie ebenso an die Dead Letters. - Der Shard bleibt für die Wartezeit stehen. Ein Shard, dessen
Entity im Backoff ist, ist nicht leer, auch wenn die Entity nicht läuft:
Der Sweep für leere Shards lässt ihn
in Ruhe, bis die Wartezeit um und nichts mehr zurückgehalten ist. Ein
shardPassivationIdleMs, das kürzer ist als die Wartezeit, verwirft also weder, was zurückgehalten wird, noch beginnt es den Backoff von vorn. - Auch ein Start wartet. Ein
StartEntityfür die Entity — etwa an eine Shard-Ref geschickt — erstellt sie, wenn ihre Wartezeit endet, nicht sofort. Ist die Wartezeit um und nichts zurückgehalten, erstellt die nächste Nachricht die Entity sofort. - Die Region erfährt vom Stopp weiterhin: Bei
rememberEntitieswird die Entity alsstoppedverzeichnet, und sie wird nicht wiederbelebt, bis eine Nachricht für sie kommt.
Die Wartezeiten verdoppeln sich und setzen sich zurück wie die des
Shards: Eine Entity, die seit ihrer Rückkehr reset-after lang nicht
ungefragt gestoppt ist, beginnt wieder bei min, und eine Passivierung
dazwischen ist kein Ausfall. Mit den ausgelieferten Werten wird eine
Entity, die bei jeder Nachricht ausfällt, etwa alle zehn Sekunden neu
erstellt: Dreißig Nachrichten im Abstand von 5 ms ergeben jetzt zwölf
Instanzen — die erste, ihre zehn Neustarts innerhalb des Budgets und
eine, wenn die Wartezeit endet — statt dreißig.
actor-ts.sharding.entity-restart-backoff { min = 200ms # the first wait after the restart budget; must be > 0 max = 10s # the doubling stops here random-factor = 0.2 # each wait spread by up to 20 % either way reset-after = 60s # no unasked stop for this long, and the next one waits min}Der Builder nimmt dieselben vier:
const shardingOptions = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((command) => command.entityId) // A cart's recovery reads a store that takes seconds to fail over: // give it one before the first retry, and at most half a minute. .withEntityRestartBackoffMinMs(1_000) .withEntityRestartBackoffMaxMs(30_000);Rebalancing
Abschnitt betitelt „Rebalancing“Wenn sich die Cluster-Topologie ändert (ein Node tritt bei oder geht) — oder wenn eine Region stoppt und sich dabei beim Koordinator abmeldet —, führt der Koordinator einen Rebalance-Lauf durch:
- Berechne die neue Shard-zu-Node-Zuordnung aus der aktiven Allokationsstrategie (Default: Hash modulo Regionen).
- Sage für jeden bewegten Shard der alten Region, sie soll den Shard übergeben.
- Die alte Region stoppt ihre Entities (die ihren State persistieren können), sagt dem Koordinator “Handoff abgeschlossen” und hört auf, für diesen Shard zu routen.
- Die neue Region spawnt Entities für diesen Shard bei Bedarf, wenn Nachrichten ankommen.
Der Handoff ist nicht sofort fertig — gepufferte Nachrichten warten auf das “Handoff abgeschlossen”-Signal, bevor sie an den neuen Besitzer weitergeleitet werden. Das verhindert, dass Nachrichten an einer halb-verschobenen Entity vorbeisausen.
Siehe Rebalance für das vollständige Protokoll.
Den Cluster verlassen
Abschnitt betitelt „Den Cluster verlassen“cluster.leave() übergibt die Shards dieses Nodes, bevor es
irgendwem sagt, dass der Node geht, und wartet darauf:
- Jede Region, die der Node gestartet hat, stoppt ihre Shards und
deren Entities. Jede Entity beendet die Nachricht, die sie gerade
bearbeitet — der Schreibvorgang einer persistenten Entity landet —
und durchläuft
postStop; danach meldet die Region dem Koordinator, dass sie weg ist, und der verteilt ihre Shards neu. - Die Koordinatoren des Nodes stoppen nach seinen Regionen, sodass ein Koordinator, der auf einem gehenden Leader noch aktiv ist, das Ende seiner eigenen Regionen mitbekommt und ihre Shards sofort neu verteilt — gemerkte Entities starten auf ihrem neuen Zuhause neu, ohne dass ihnen etwas geschickt wird.
- Erst dann wechselt der Node zu
leavingund benachrichtigt seine Peers.
So verteilt kein Peer einen Shard neu, solange er hier noch läuft: Ein
Shard hat nie zwei lebende Zuhause, und eine persistente Entity nie
einen zweiten Schreiber. Das Warten ist durch das hand-off-timeout
jedes Typs begrenzt. Eine Region, die bis dahin nicht gestoppt hat —
eine Entity, die in ihrem Handler hängt, hält sie auf —, wird
angewiesen, sofort zu stoppen, eine Warnung nennt sie, und das
Verlassen geht ohne sie weiter; bis sie weg ist, kann diese eine
Entity noch laufen, wenn ihr neues Zuhause sie startet.
Die Coordinated-Shutdown-Pipeline tut dasselbe in ihrer Phase
cluster-sharding-shutdown-region, vor cluster-leave. Ein Node,
den seine eigene Downing-Entscheidung entfernt hat, oder einer, der
seinen Join aufgegeben hat, geht stattdessen sofort und stoppt sein
Sharding neben dem Abgang: Die Peers, die ihn entfernt haben, warten
auf keine Übergabe.
Sobald leave() aufgelöst ist, sind die Namen der Regionen und
Koordinatoren wieder frei, sodass ein erneuter Beitritt auf demselben
ActorSystem dieselben Typen über das sharding des neuen Clusters
startet. Die Fassade des verlassenen Clusters verweigert jeden Start:
Darüber gestartete Aktoren wären an einen Cluster gebunden, den es
nicht mehr gibt.
Eine Nachricht, die unterwegs zum gehenden Node ist, während die Übergabe läuft, wird nicht zum neuen Zuhause mitgenommen — sie geht verloren, wie bei jeder Region, die stoppt. Die Übergabe bewegt Shards, keine Nachrichten im Flug.
State über Failover
Abschnitt betitelt „State über Failover“Sharded Entities unterliegen denselben Neustart-Semantiken wie jeder andere Actor — wenn eine Entity zu einem neuen Node wandert, startet die neue Instanz mit weißer Weste.
Für State, der überleben soll:
PersistentActor— die Entity persistiert Events in einem Journal; auf einem frischen Node spielt sie das Journal beim Start ab. Siehe PersistentActor.DurableStateActor— einfacher: persistiere den aktuellen State-Snapshot; restore beim Neustart. Siehe DurableState.DistributedData— für State, der von jedem Node lesbar sein soll (nicht nur vom aktuellen Host der Entity), nutze ein CRDT im DD-Replicator stattdessen.
Ohne eine dieser Lösungen gibt dir Sharding Platzierung und Routing, aber keine Durability.
Die eigene Karte des Coordinators
Abschnitt betitelt „Die eigene Karte des Coordinators“Der Coordinator hält wo jeder Shard lebt im Speicher, und ein neuer Leader
beginnt mit einer leeren Karte, die er aus den Registrierungen der Regions
wieder aufbaut. actor-ts.sharding.persist-coordinator-state = on (oder
withPersistCoordinatorState()) hält diese Karte stattdessen im Journal der
Persistence-Extension, sodass ein neuer Leader — oft ein gerade neu
gestarteter Node, weil der Leader die niedrigste Adresse ist — mit der Karte
beginnt, die der vorige zuletzt geschrieben hat (#1188):
actor-ts.sharding { persist-coordinator-state = on coordinator-state-load-timeout = 10s}Das Journal muss eine Datenbank für den ganzen Cluster sein — der nächste Leader liest, was der vorige geschrieben hat —, deshalb wird ein node-lokales Journal auf einem Node, der entfernte Peers erwartet, beim Start des Typs abgelehnt. Gehalten wird nur die jüngste Karte: Jedes Speichern kompaktiert die vorige, und ein Speichern von einem Coordinator, dessen Sicht auf den Stream veraltet ist, schlägt fehl, statt zu überschreiben.
Die Platzierung wartet nach einem Leader-Wechsel trotzdem auf die eigenen
Ansprüche der Regions: Die Karte kann der letzten Zuteilung hinterherhinken,
und erst die Registrierung einer Region belegt, was sie wirklich betreibt.
Was die Karte beiträgt, sind die Regions selbst — ein neuer Leader bittet jede,
die sie nennt, sich zu registrieren — und die Homes von Shards, die noch
niemand beansprucht hat. Ein neuer Leader wartet höchstens
coordinator-state-load-timeout auf das Laden der Karte und platziert danach
ohne sie.
Wann zu Sharding greifen
Abschnitt betitelt „Wann zu Sharding greifen“Drei gute Anwendungen:
- Per-User-/Per-Tenant-State, der zu viel für einen Node ist, aber nicht von überall gleichzeitig lesbar sein muss.
- Per-Entity-Workflows — Sagas, Order-Processing, lange laufende Koordinatoren — die von Per-Key-Serialisierung profitieren.
- Hotspots, die Keys folgen — eine Streaming-Pipeline, in der die Events jedes Users in Reihenfolge auf einem einzelnen Actor verarbeitet werden sollen.
Wann NICHT Sharding verwenden
Abschnitt betitelt „Wann NICHT Sharding verwenden“Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Introspektion — die Shards auflisten, eine Ref auf einen Shard oder eine Entity holen, der Karte folgen.
- Allokationsstrategie — Default Hash-mod-Regions, eigene Strategien.
- Rebalance — das Handoff-Protokoll.
- Remember Entities — persistentes Entity-Registry für schnelle Recovery.
- Singleton-Überblick — für ein-Actor-clusterweit.
- Sharded Daemon Process — Worker in fester Anzahl, verteilt per Sharding.
Die API-Referenzen ClusterSharding und
ShardRegion decken die vollständige
Oberfläche ab, inklusive des Per-Node-Region-Actors.
