Zum Inhalt springen
Deutsch

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.

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.

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 3

Das ist absichtlich — der Remember-Store hat andere Zugriffsmuster (kleine, häufige Writes, wenn Entities starten/stoppen) und profitiert davon, separierbar zu sein.

  • 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 PersistentActor oder externen Storage.

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.

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:

  1. Ein Write, wenn die Entity spawnt (ein append eines started-Events).
  2. Ein Write, wenn die Entity passiviert / stoppt (ein append eines stopped-Events).

Für High-Churn-Entities (Millionen kurzlebiger Sessions pro Stunde) ist das echter Overhead. Erwäge:

  • rememberEntities fü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 append ein 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.

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.

SzenariorememberEntities nutzen?
Per-User-Sessions, kurzlebig, beim nächsten Request neu spawnenNein
Lange laufende Koordinatoren, müssen leben, um geplante Arbeit zu tunJa
IoT-Device-Handler, müssen beim Start MQTT-Topics abonnierenJa
Per-Tenant-Cache, teuer zu rebauenJa
Per-Order-Saga, muss nach Failover dort weiter, wo sie aufgehört hatJa
Per-Request-temporärer-Actor, stirbt in SekundenNein

Die Regel: wenn “brauche ich diese Entity am Leben auch ohne kürzliche Nachricht?” ein Ja ist, aktivieren.

Passivierung stoppt idle Entities. Mit rememberEntities:

Entity aktiv → passiviere (idle) → Entity stoppt → Store: append stopped?

Verhalten des Frameworks:

  • Idle-Timeout-Passivierung (passivationIdleMs) — hängt ein stopped-Event an. Nächste Nachricht spawnt sie neu; der Store empfängt erneut ein started-Event.
  • maxEntities-Passivierung — dasselbe.
  • Passivate von 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 schlichtes stopSelf — hängt ebenfalls ein stopped-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 ihr entity-restart-backoff es erlaubt: Eine Nachricht innerhalb der Wartezeit wird bis zu deren Ende zurückgehalten.

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.

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.