Remember Entities
Sharded Entities sind standardmäßig lazy: ein Entity-Actor
existiert erst, nachdem er seine erste Nachricht empfangen hat.
Ohne rememberEntities bedeutet ein Cluster-Kaltstart oder
Koordinator-Failover, dass die aktive Entity-Menge leer ist —
Entities werden bei Bedarf neu gespawnt, sobald Nachrichten
ankommen.
Für viele Workloads ist das in Ordnung. Manchmal aber willst du, dass Entities eager neu erstellt werden:
- Sie haben geplante Hintergrundarbeit, die unabhängig von eingehenden Nachrichten laufen sollte.
- Sie haben etwas Externes abonniert und müssen am Leben sein, um es zu verarbeiten.
- Failover sollte das volle Arbeitsset sofort wiederherstellen, nicht durchsickern, sobald Nutzer auf jede Entity treffen.
rememberEntities: true ist der Schalter.
Aktivieren
Abschnitt betitelt „Aktivieren“const startShardingOptions = StartShardingOptions.create() .withTypeName('session') .withEntityActor(SessionActor) .withExtractEntityId((message) => message.userId) .withRememberEntities(true);sharding.start( startShardingOptions,);Was es tut:
- Die Existenz jeder Entity (ihre ID) wird in einem Remember-Entities-Store persistiert.
- Beim Cluster-Kaltstart oder nach einem Koordinator-Failover liest der Koordinator die Menge bekannter Entity-IDs und bittet jede Shard-Region, sie eager neu zu spawnen.
Der Default-Store nutzt das Journal des
Systems, sodass du das umsonst bekommst, sobald Persistenz
konfiguriert ist. Überschreibe mit rememberEntitiesStore, wenn du
einen anderen Backing-Store brauchst.
Was persistiert wird
Abschnitt betitelt „Was persistiert wird“Nur die Identitäten aktiver Entities — nicht ihr Zustand. Der Entity-Zustand ist die Verantwortung der Entity selbst (PersistentActor journalisiert Zustandsänderungen; Remember-Entities verfolgt, welche IDs zurückgebracht werden sollen).
Zwei-Speicher-Aufteilung:
Journal (deine Events) RememberEntitiesStore (nur IDs) persistenceId=cart-user-42 entityIds = ['cart-user-42', 'cart-user-43', ...] Event 1 Event 2 Event 3Das ist absichtlich — der Remember-Store hat andere Zugriffsmuster (kleine, häufige Writes, wenn Entities starten/stoppen) und profitiert davon, separierbar zu sein.
Was NICHT persistiert wird
Abschnitt betitelt „Was NICHT persistiert wird“- Der Shard, zu dem eine gegebene Entity gehört hat. Bei Respawn läuft die Allokation erneut (per Allokationsstrategie).
- Der Zustand der Entity. Wenn du willst, dass Zustand
überlebt, muss die Entity ihn selbst persistieren — über
PersistentActoroder externen Storage.
Ohne Persistenz-Backend
Abschnitt betitelt „Ohne Persistenz-Backend“Wenn du rememberEntities: true verwendest, aber kein Journal
konfiguriert hast:
const startShardingOptions = StartShardingOptions.create() .withTypeName('...') .withEntityActor(...) .withExtractEntityId(...) .withRememberEntities(true) .withRememberEntitiesStore(null);sharding.start( startShardingOptions, // explizites Opt-Out aus Persistenz);null zu übergeben fällt zurück auf das v1-In-Memory-Only-Verhalten —
die Entity-Menge wird im Prozessspeicher verfolgt und bei
Koordinator-Failover verloren. Nützlich für Dev / Tests; sinnlos
in Produktion.
Ohne rememberEntitiesStore: null und ohne expliziten Store
instanziiert das Framework automatisch einen
JournalRememberEntitiesStore mit dem System-Journal — was zum
Testen in Ordnung ist, aber mit dem In-Memory-Default einen
Neustart nicht überlebt. Stelle sicher, dass dein Journal in
Produktion dauerhaft ist — und geteilt: auf diesem Auto-Pfad
lässt ein Journal, das node-lokalen Storage deklariert (eine
SQLite-Datei, der In-Memory-Default), in einem Cluster mit
Remote-Peers sharding.start mit StorageLocalityError
fehlschlagen, statt die Registry still zu forken. Die Auswege
stehen im Fehler selbst: ein geteiltes Journal verdrahten, einen
expliziten Store übergeben (z. B.
CassandraRememberEntitiesStore) oder
rememberEntitiesStore: null setzen.
Eigener Store
Abschnitt betitelt „Eigener Store“import type { RememberEntitiesStore, RememberEvent } from 'actor-ts/cluster';
class RedisRememberEntitiesStore implements RememberEntitiesStore { async append(typeName: string, event: RememberEvent): Promise<void> { /* RPUSH das Event als JSON */ } async load(typeName: string): Promise<RememberEvent[]> { /* LRANGE 0 -1 → jeweils JSON.parse */ return []; } async clear(typeName: string): Promise<void> { /* DEL den Key */ }}
const shardingOptions = StartShardingOptions.create() // ... .withRememberEntities(true) .withRememberEntitiesStore(new RedisRememberEntitiesStore());sharding.start(shardingOptions);Die Schnittstelle ist klein. Nützlich, wenn du die Entity-Registry auf einem anderen Backing-Store als den Rest deiner Persistenz willst (z. B. Redis für latenzarme Entity-Set-Lookups, während das Journal auf Cassandra liegt).
rememberEntities: true fügt zwei Write-Operationen pro
Entity-Lebenszyklus hinzu:
- Ein Write, wenn die Entity spawnt (ein
appendeinesstarted-Events). - Ein Write, wenn die Entity passiviert / stoppt (ein
appendeinesstopped-Events).
Für High-Churn-Entities (Millionen kurzlebiger Sessions pro Stunde) ist das echter Overhead. Erwäge:
rememberEntitiesfür kurzlebige Workloads überspringen.- Einen schnellen Store (In-Memory-Redis) statt des Default-Journals nutzen.
- In einem eigenen Store nicht aufs Batchen setzen: der Coordinator
übergibt
appendein Event nach dem anderen, und das nächste erst, wenn das vorige abgeschlossen ist — ein Store hat also nichts zu batchen, bis das Store-Interface einen Batch-Einstiegspunkt bekommt.
Für Low-Churn-Workloads (10K stabile Entities) sind die Kosten vernachlässigbar.
Einen Restore drosseln
Abschnitt betitelt „Einen Restore drosseln“Das Zurückkommen ist die teure Hälfte, und per Default passiert es auf einen Schlag. Bekommt eine Region einen Shard zugeteilt, wird ihr dessen komplettes Register zugeschickt, und sie spawnt jede Entität daraus in einem Durchgang — für jeden Shard, den sie bekommt. Ein Node-Neustart oder ein Rebalance nach einem Node-Ausfall öffnet damit einen Journal-Replay pro erinnerter Entität im selben Tick. Bei ein paar hundert Entities ist das unproblematisch. Bei Zehntausenden ist es ein Ansturm auf den Store, genau in dem Moment, in dem der Cluster am wenigsten gesund ist.
entityRecoveryStrategy: 'constant-rate' verteilt diese Starts:
const shardingOptions = StartShardingOptions.create<DeviceCommand>() .withTypeName('device') .withEntityActor(DeviceEntity) .withExtractEntityId((command) => command.deviceId) .withRememberEntities() .withEntityRecoveryStrategy('constant-rate') .withEntityRecoveryConstantRateFrequencyMs(100) .withEntityRecoveryConstantRateNumberOfEntities(5);
cluster.sharding.start(shardingOptions);oder für das ganze Deployment auf einmal:
actor-ts.sharding.entity-recovery { strategy = constant-rate constant-rate.frequency = 100ms constant-rate.number-of-entities = 5}Drei Eigenschaften solltest du kennen, bevor du danach greifst.
Das Budget gilt regionsweit, pro Sharded Type. Fünf Entities pro
100 ms sind fünf für diesen Sharded Type auf diesem Node, egal wie viele
Shards der Node gerade hält. Jeder Sharded Type, den ein Node startet,
läuft in einer eigenen Region mit eigener Queue — ein Node, der einen
device- und einen order-Typ wiederherstellt, startet mit diesen
Einstellungen also bis zu zehn pro Fenster, fünf von jedem. Das
entsprechende Akka-Setting liest sich anders — dort gilt die Rate pro
Shard, ein Node mit 21 von 64 Shards erholt also 21 × die konfigurierte
Zahl pro Fenster. Regionsweit ist dieselbe Entscheidung, die
maxEntities aus demselben Grund und mit demselben Geltungsbereich
trifft: eine Schranke, die die Shard-Anzahl multipliziert, ist keine, die
jemand gewählt hat.
Es drosselt Starts, keine Replays. Jede gespawnte Entität repliziert
asynchron; ein Replay, der länger dauert als das Fenster, überlappt also
weiterhin den nächsten Batch. Dieser Key glättet die Ankunftsrate; wie
viele Recoveries gleichzeitig laufen dürfen, begrenzt eine Ebene tiefer
actor-ts.persistence.max-concurrent-recoveries
(per Default 50, systemweit). Beides greift ineinander: das Drosseln
entscheidet, wie schnell Entities entstehen, das Permit, wie viele ihrer
Replays gleichzeitig das Journal lesen.
Nichts geht verloren. Der Rückstand wird abgearbeitet, bis jede erinnerte Entität wieder da ist, und eine Nachricht an eine Entität, die noch in der Queue wartet, erzeugt sie sofort — nur der Recovery-Schwall wartet, nie der Live-Traffic. Auch einen Shard kostet eine lange Queue nichts: Der Sweep für leere Shards lässt einen Shard in Ruhe, solange eine seiner erinnerten Entitäten noch auf ihren Zug wartet, und der Batch, der sie schließlich startet, ist kein Grund, den Shard beim nächsten Sweep zu stoppen — der Shard selbst lehnt das Stoppen ab, solange er die Entität betreibt, die der Batch gerade gestartet hat.
Der Default ist 'all', das oben beschriebene Verhalten. Drosseln
verändert, wann eine Entität zurückkommt, und wie schnell dein Journal
die Replays verträgt, ist eine Eigenschaft deines Journals — also eine
Entscheidung, die du triffst, statt sie zu erben.
Wann verwenden
Abschnitt betitelt „Wann verwenden“| Szenario | rememberEntities nutzen? |
|---|---|
| Per-User-Sessions, kurzlebig, beim nächsten Request neu spawnen | Nein |
| Lange laufende Koordinatoren, müssen leben, um geplante Arbeit zu tun | Ja |
| IoT-Device-Handler, müssen beim Start MQTT-Topics abonnieren | Ja |
| Per-Tenant-Cache, teuer zu rebauen | Ja |
| Per-Order-Saga, muss nach Failover dort weiter, wo sie aufgehört hat | Ja |
| Per-Request-temporärer-Actor, stirbt in Sekunden | Nein |
Die Regel: wenn “brauche ich diese Entity am Leben auch ohne kürzliche Nachricht?” ein Ja ist, aktivieren.
Interaktion mit Passivierung
Abschnitt betitelt „Interaktion mit Passivierung“Passivierung stoppt idle Entities. Mit rememberEntities:
Entity aktiv → passiviere (idle) → Entity stoppt → Store: append stopped?Verhalten des Frameworks:
- Idle-Timeout-Passivierung (
passivationIdleMs) — hängt einstopped-Event an. Nächste Nachricht spawnt sie neu; der Store empfängt erneut einstarted-Event. maxEntities-Passivierung — dasselbe.Passivatevon der Entity selbst — dasselbe.- Ein Stopp ohne
Passivate— ein Ausfall jenseits des Neustart-Budgets des Shards, ein Recovery-Fehler, den die Entity verschluckt hat, ein verlorenes Lease, ein schlichtesstopSelf— hängt ebenfalls einstopped-Event an; die Entity wird also nicht aus der Registry wiederbelebt. Sie kommt mit der nächsten Nachricht für sie zurück, frühestens wenn ihrentity-restart-backoffes erlaubt: Eine Nachricht innerhalb der Wartezeit wird bis zu deren Ende zurückgehalten.
Erinnerte Entities zählen gegen maxEntities
Abschnitt betitelt „Erinnerte Entities zählen gegen maxEntities“Eine erinnerte Entity wird vorab erzeugt: die Region bekommt die Registry
eines Shards und startet jede Entity darin, ohne dass irgendetwas dorthin
geroutet worden wäre. Diese Starts laufen jetzt durch dasselbe Cap und dieselbe
Ersetzungsstrategie wie ein nachrichtengetriebener Start — ein Node, dem eine
Registry größer als maxEntities gereicht wird, passiviert also auf das Cap
herunter, statt es um die Größe der Registry zu überschreiten und dort zu
bleiben.
Das gehört mit entity-recovery zusammengedacht,
wenn die beiden nicht zueinander passen: bei kleinem Cap und großer Registry
spawnt ein ungedrosselter all-Restore jede Entity und passiviert die meisten
sofort wieder. Entweder hebst du das Cap über die Registry, die ein Node halten
soll, oder du akzeptierst, dass das Cap die tatsächliche Grenze ist und die
Registry eine Obermenge dessen, was resident bleibt.
Für Workloads, in denen du eager Re-Spawn auch von kürzlich
inaktiven Entities willst, setze passivationIdleMs: 0, damit
sie bleiben.
Nach einem unerwarteten Shard-Tod
Abschnitt betitelt „Nach einem unerwarteten Shard-Tod“Ein Shard-Actor kann außerhalb eines Rebalance sterben — etwa weil eine
Entity einen Fehler an ihn eskaliert hat, worauf die Region den Shard
stoppt. Die Region behält die Ownership, wartet den Failure-Backoff des
Shards ab (shard-failure-backoff, beim ersten Mal etwa 200 ms), erstellt
den Shard neu und fragt dann beim Koordinator nach, was er sich für ihn
merkt, sodass die Entities von allein zurückkommen, ohne auf Verkehr zu
warten. Es wird dabei nichts als stopped verzeichnet: die Entities
sollten nie gehen.
Ein Shard, der immer wieder stirbt, läuft nicht in eine Schleife. Jeder
Tod in Folge verdoppelt die Wartezeit, bis max (standardmäßig 10 s),
und nach der Registry wird erst gefragt, wenn der Shard zurückkommt.
Vor dem Backoff wurde ein Shard, dessen Entity bei jedem Start
ausfiel, auf die Antwort des Koordinators hin neu erstellt — tausende
Male pro Sekunde und ganz ohne Verkehr —, und jede Runde hängte einen
started-Eintrag an den Store an. Siehe
wenn Shards und Entities immer wieder ausfallen
für das Gesamtbild.
Shard-Passivierung berührt die Registry gar nicht — passiviert wird
immer nur ein leerer Shard, und seine Entities haben ihre eigenen
stopped-Events zu diesem Zeitpunkt längst gemeldet. Der Shard bestätigt
selbst, dass er leer ist, bevor er geht, sodass eine erinnerte Entity, die
ein Recovery-Batch gerade gestartet hat, nie mit ihm gestoppt wird.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Sharding-Überblick — das größere Bild.
- Rebalance — was passiert, wenn gemerkte Entities wandern.
- PersistentActor — für die Zustands-Recovery der Entity (orthogonal zu Remember-Entities).
- Journals — der Default-Backing-Store.
