Zum Inhalt springen
Deutsch

Mailbox-Sizing

Die Default-Mailbox eines Actors ist unbounded. Auf dem Weg hinein wird nichts verworfen, und die Queue wächst, bis der Actor sie abarbeitet. Eine zu begrenzen ist eine Entscheidung pro Actor, denn es ist eine Entscheidung, Nachrichten zu verlieren — du triffst sie dort, wo du sagen kannst, welche verzichtbar sind.

Diese Seite ist der Entscheidungs-Guide für Produktions-Mailbox-Sizing.

const ref = system.spawnAnonymous(Worker);
// ↑ unbounded FIFO-Mailbox — auf dem Weg hinein wird nie etwas verworfen

Unbounded ist der ehrliche Default: ein Actor-Framework kann nicht wissen, welche deiner Nachrichten entbehrlich ist — und zwischen v0.10 und v0.15 hat dieses geraten. Es begrenzte jede Mailbox auf 10 000 mit drop-head, ein zurückfallender Actor verlor also still seine älteste wartende Nachricht. Für einen Sensorwert ist das richtig, für ein Terminated-Signal, eine Delivery-Bestätigung oder ein WebSocket-close falsch. Alle drei liefen durch dieselbe Queue, und aus jedem wurde ein gemeldeter Defekt.

Zwei der drei sind inzwischen endgültig vom Tisch. Ein Terminated der Death Watch kommt über eine Spur an, die keine Overflow-Policy abwerfen und kein Throttle verwerfen kann — eine Schranke, die du setzt, kostet den Actor also seinen Backlog, nie die Tode, auf die er wartet. Ein WebSocket-close nimmt dieselbe Spur, eine begrenzte Verbindung kann closeAll() also nicht in einen Socket verwandeln, der still offen bleibt. Die Delivery-Bestätigung ist weiterhin eine Anwendungsnachricht, und dort gilt der Satz oben unverändert.

Die Obergrenze, die dieser Handel erkaufte, gab es ohnehin nicht: nur die User-Queue war begrenzt. System-Nachrichten waren nie gedeckelt, der Prozess konnte den Heap also trotzdem ausschöpfen.

Was du stattdessen bekommst, ist Wachstum, von dem du erfährst:

  • Ein Actor, dessen Queue 10 000 Nachrichten erreicht, loggt eine Warnung — und erneut bei jeder Verdopplung: 20 000, 40 000 und so weiter. Das läuft immer, ohne Metrik-Stack.
  • Mit aktivierten Metriken meldet actor_mailbox_size{class, path} die Tiefe jeder Mailbox ab derselben Marke.

Der Fehlermodus, den eine unbegrenzte Queue weiterhin erreichen kann — erschöpfter Heap, lange GC-Pausen, ein Producer, der nie erfährt, dass es ein Problem gibt — kündigt sich also lange vorher an. Achte auf die Warnung; begrenze die Actors, die sie produzieren.

Tiefe ist kein Durchsatzproblem. Beide Queues in einer Mailbox sind Ring-Buffer: die nächste Nachricht zu entnehmen rückt einen Index vor, statt den Backlog dahinter neu zu indizieren — eine Queue von einer Million kostet pro Nachricht dasselbe wie eine von zehn. Was eine tiefe Queue sehr wohl kostet, ist Speicher und Latenz: jede Nachricht darin wird gehalten, und die hinterste wartet auf alles, was vor ihr liegt. Das sind die Gründe zu begrenzen, und keiner davon wird durch eine schnellere Queue behoben.

Drei Muster, in denen eine unbegrenzte Queue die falsche Antwort ist. In jedem sind Kapazität und Policy bewusste Entscheidungen:

import { ActorOptions } from 'actor-ts';
// Langsamer Consumer: schreibt 10/sec auf Disk; Producer pusht 1000/sec
const writerOptions = ActorOptions.create()
.withMailbox(() => new BoundedMailbox({
capacity: 1_000,
overflow: 'reject',
}));
const slowWriter = system.spawnAnonymous(SlowWriter, writerOptions);

Bounde auf den Worst-Case-akzeptablen Puffer. reject propagiert Backpressure zum Sender — er sieht MailboxFullError und passt sich an (Retry, Drop, Alert).

2. Telemetrie-artige Actors (veraltete Daten sind falsch)

Abschnitt betitelt „2. Telemetrie-artige Actors (veraltete Daten sind falsch)“
import { ActorOptions } from 'actor-ts';
const telemetryOptions = ActorOptions.create()
.withMailbox(() => new BoundedMailbox({
capacity: 5_000,
overflow: 'drop-head',
}));
const telemetry = system.spawnAnonymous(MetricsAggregator, telemetryOptions);

Für Metriken, Sensorwerte, Status-Pings — frischer ist besser. drop-head verwirft die älteste wartende Nachricht, wenn neue ankommen, und hält die Queue mit aktuellen Daten gefüllt.

import { ActorOptions } from 'actor-ts';
const authOptions = ActorOptions.create()
.withMailbox(() => new BoundedMailbox({
capacity: 10_000,
overflow: 'drop-new',
}));
const auth = system.spawnAnonymous(AuthActor, authOptions);

drop-new verwirft eingehende Nachrichten, wenn voll — bewahrt bereits eingereihte Arbeit. Richtig, wenn “die Queue, die ich habe, ist die Arbeit, die mich interessiert” gilt — teilweiser Denial of Service ist besser, als gar nichts zu verarbeiten.

Die drei Fälle oben sind Entscheidungen an einer Spawn-Stelle, getroffen von jemandem, der den Verkehr dieses Actors kennt. Es gibt einen vierten, und der gehört dem Betrieb und nicht dem Code: ein speicherbeschränktes Deployment, in dem eine unbegrenzte Queue überall der falsche Fehlermodus ist — und in dem die Spawn-Stellen nicht deine sind.

actor-ts.mailbox.default {
capacity = 50000 # 0 (der Default) = keine globale Schranke
overflow = "drop-head"
}

Lies das als „begrenze jeden Actor, den deine Anwendung geschrieben hat“. Wer die Klasse geschrieben hat ist der Maßstab, nicht wo der Actor im Baum hängt — eine Sharded Entity wird von ihrem Shard gespawnt, ein Cluster Singleton von seinem Manager, beide unter /system, und beide sind deine Klassen; die Schranke erreicht sie also. Das ist Absicht: ein speicherbeschränktes Sharding-Deployment ist der Fall, für den es diesen Key gibt, und seine Entities sind meist die größte Actor-Population auf dem Knoten. Es ist dieselbe BoundedMailbox, die die drei Fälle oben bauen, nur unter der Spawn-Stelle eingezogen: ein Actor mit withMailboxCapacity() behält seine eigene Zahl, ein Actor mit withMailbox() behält seine eigene Queue, ein Actor, den ein Eintrag pro Pfad nennt, übernimmt den des Eintrags (Fall 5), alle anderen übernehmen das hier. (Ein WebSocket-Hub übernimmt es auf der Control-Aware-Queue, die er standardmäßig bekommt, und die wendet die Schranke auf seine Frames an, nicht auf seine Control-Nachrichten — siehe unten.)

Was es nicht begrenzt — und die Grenzen zählen hier mehr als die Zahl:

  • Die eigenen Actors des Frameworks. Shard-Regions, Coordinators und Shards, Singleton-Manager, der Cluster-Event-Stream, der Pub-Sub-Mediator, der Reliable-Delivery-Producer, Projections, der DevTools-Hub. Ihren Verkehr abzuwerfen würde Invarianten brechen, nach denen deine Anwendung nie gefragt hat. Nicht der Pfad nimmt sie aus: ein Shard ist ausgenommen, die Entity darunter nicht — und eine Framework-Klasse, die als Entity läuft, ist eine Entity: der Host, in dem ShardedDaemonProcess jeden Daemon laufen lässt, ist begrenzt wie jede andere.
  • Keinen undroppable Envelope. Ein Death-Watch-Terminated, das Kommando, das einen aufgewerteten Socket an seinen Hub übergibt, und das close einer Verbindung nehmen eine Spur, die keine Overflow-Policy abwerfen kann. Ein begrenzter Actor erfährt weiterhin, dass das, was er beobachtet hat, gestorben ist.
  • Keine Control-Nachrichten eines WebSocket-Hubs. Ein Hub, der ohne eigene Mailbox gespawnt wurde, hat eine Control-Aware-Queue, und zwei Nachrichten fahren auf ihrer Control-Spur: dasselbe Accept-Kommando und das Signal websocket-connected, das der Actor der neuen Verbindung meldet. Die Schranke zählt sie weder mit noch wirft sie sie ab; ein begrenzter Hub führt also weiterhin jeden Client, den er angenommen hat.
  • Die overflow-Hälfte nicht, solange nichts begrenzt ist. mailbox.default.overflow ist die systemweite Policy für jede begrenzte Mailbox; für sich allein begrenzt sie nichts.

Und eines, das es tut und das man vorher wissen sollte: das Framework liefert auch Actors aus, die dein Code spawnt — den WebSocket-Hub (WebsocketServerActor) und die Verbindungen, die er annimmt, die Broker-Adapter (KafkaActor, MqttActor, NatsActor, AmqpActor, JetStreamActor, RedisStreamsActor, SseActor, EmailBridgeActor), die TCP- und UDP-Socket-Actors sowie den gRPC-Client und -Server. Von dir gespawnt liegen sie innerhalb der Schranke wie alles andere, was du spawnst. Das Accept-Kommando, das Signal websocket-connected und das Close-Kommando überstehen sie (siehe oben), der restliche Verkehr eines Hubs nicht — seine Frames und das Signal websocket-disconnected werden abgeworfen wie jede andere Nachricht; siehe die Warnung am Ende dieser Seite.

Zwischen der Spawn-Stelle und dem ganzen Deployment liegt der Fall, in dem der Betrieb weiß, welche Actors eine Schranke brauchen, und trotzdem nicht ändern kann, wo sie gespawnt werden: ein heißer Ingest-Actor, die Routees eines Pools, die Verbindungen einer WebSocket-Route, die Entities eines Sharding-Typs. actor-ts.deployment nennt sie über ihren Pfad:

actor-ts.deployment {
"/user/ingest" { mailbox-capacity = 10000, mailbox-overflow = "drop-new" }
"/user/pool/routee-*" { mailbox-capacity = 500 }
"/user/chat/ws-*" { mailbox-capacity = 256 }
"/system/cluster/sharding/region-orders/**" { mailbox-capacity = 5000 }
}

Ein exakter Pfad nennt einen Actor. Ein * trifft innerhalb eines Segments — so erreicht man die Routees, die ein Router routee-1, routee-2, … nennt, und die Verbindungen, die ein Hub ws-1, ws-2, … nennt; ein Segment, das genau ** ist, reicht in jede Tiefe — so erreicht man die Entities eines Sharding-Typs unter seiner Region. Der Eintrag liegt zwischen der Spawn-Stelle und actor-ts.mailbox.default: das eigene withMailboxCapacity() oder withMailbox() eines Actors gewinnt weiterhin, und der Eintrag gewinnt gegen die globale Schranke — in beide Richtungen, denn mailbox-capacity = 0 nimmt die Pfade, die er nennt, von einer globalen Kapazität aus:

actor-ts.mailbox.default.capacity = 50000
actor-ts.deployment { "/user/audit-log" { mailbox-capacity = 0 } } # never shed

Was ein Eintrag nie erreicht, ist, was auch die globale Schranke nie erreicht: die eigenen Actors des Frameworks, egal was der Key sagt — "/system/**" begrenzt die Entities und Singleton-Instanzen unter /system und lässt Regions, Shards und Coordinators in Ruhe — und keinen undroppable Envelope. Für einen Actor gilt ein Eintrag, der spezifischste Treffer, als Ganzes; die Konfigurationsreferenz nennt die Rangfolge und die Keys, mit denen das System nicht startet.

Drei Faktoren:

  1. Worst-Case-Burst-Größe — wieviele Nachrichten im Worst-Case-Fenster ankommen, bevor der Consumer drainen kann.
  2. Speicher pro Nachricht — capacity × bytes_per_message begrenzt die Speicherkosten der User-Queue. Die System-Spur wird bewusst nie gedeckelt — diese Rechnung begrenzt also den Teil der Mailbox, den du konfigurierst, nicht den Speicherbedarf des Actors; siehe Mailboxes.
  3. Latenz-Budget — capacity / drain_rate begrenzt die Worst-Case-Latenz, die eine Nachricht vor der Verarbeitung wartet.

Für einen Worker, der 100 msg/sec verarbeitet und Bursts bis zu 1000 msg in 1 Sekunde erwartet:

capacity = 1000 # Worst-Case-Burst
Worst-Case-Latenz = 1000 / 100 = 10s # bei voller Queue

Wenn 10 Sekunden Queue okay sind, ist Kapazität 1000 fein. Wenn nicht, Kapazität reduzieren oder akzeptieren, dass Producer MailboxFullError sehen.

Stock-Metriken (Stock-Metriken) exponieren die Mailbox-Tiefe:

actor_mailbox_size{class="Worker", path="..."}
actor_mailbox_depth_bucket
actor_mailbox_wait_seconds_bucket
actor_mailbox_dropped_total{class="Worker", reason="drop-head"}

Beobachte:

  • actor_mailbox_size — die Tiefe jeder Mailbox ab 10 000 wartenden Nachrichten. Eine Serie entsteht erst, wenn ein Actor diese Marke überschreitet — ihr Vorhandensein ist also das Signal; auf einem gesunden System ist die Metrik leer. Eine geleerte Mailbox verliert ihre Serie, statt auf ihrem letzten Ausschlag stehen zu bleiben — alarmiere also auf der Existenz der Serie, nicht auf einem Übergang nach 0.
  • actor_mailbox_depth — dieselbe Größe als Verteilung, und sie deckt den Bereich ab, in dem das Gauge stumm ist. Das ist die Metrik, aus der du eine Kapazität ableitest: Eine capacity ist eine Wette auf den schlimmsten Ausschlag, und das p99 des Histogramms ist die Messung dieses Ausschlags. Seine letzte Bucket-Grenze ist die Schwelle von 10 000 des Gauges, beide decken also alles dazwischen ab — das Histogramm sagt dir, wie tief, das Gauge sagt dir, wer. Es hat keine Labels und kostet damit dasselbe, ob du zehn Actors betreibst oder zehntausend geshardete Entities.
  • actor_mailbox_wait_seconds — wie lange Nachrichten tatsächlich auf ihre Zustellung gewartet haben. Das ist das frühere der beiden Rückstau-Signale und das, auf das du alarmieren solltest: die Tiefe hat eine Schwelle von 10 000 Nachrichten, bevor sie überhaupt etwas meldet, während die Wartezeit zu steigen beginnt, sobald ein Actor nicht mehr mitkommt. Sie hat keine Labels, sagt dir also dass das System zurückfällt, nicht welcher Actor — kombiniere sie, sobald sie anschlägt, mit der Tiefe, die den path trägt.
  • actor_mailbox_dropped_total — ungleich Null mit drop-head / drop-new ist bei den Actors beabsichtigt, die du begrenzt hast; bei jedem anderen sollte sie gar nicht auftauchen. Aggregiert pro Klasse, nicht pro Actor — die beiden Metriken unterscheiden sich hier bewusst: eine Tiefen-Serie existiert nur für einen Actor, der bereits in Schwierigkeiten steckt, eine Drop-Serie dagegen für jeden Actor, der seine Arbeit tut. Für Drop-Zahlen pro Instanz nimm ein eigenes onDrop; es bekommt neben dem Grund auch den verworfenen Envelope, kann also sagen was verloren ging und nicht nur wie viel.
  • MailboxFullError-Rate beim Sender — taucht meist als Supervisor-Restarts des sendenden Actors auf.

Dieselbe 10 000er-Schwelle erzeugt eine Log-Warnung, wiederholt bei jeder Verdopplung, unabhängig davon ob Metriken aktiv sind. Auf diese Zeile alarmierst du, wenn du keinen Metrik-Stack betreibst.

Ein Zähler sagt, wie viel abgeworfen wurde. Er sagt nicht, was: ein verworfener Telemetrie-Messwert und ein verworfenes Command mit offenem Callback sind dasselbe Inkrement. deadLetterDrops schließt diese Lücke, indem es jeden verworfenen Envelope an die Dead Letters leitet, wo er seine Nutzlast und seinen Sender behält:

import { ActorOptions, BoundedMailbox, BoundedMailboxOptions } from 'actor-ts';
const commandMailbox = BoundedMailboxOptions.create()
.withCapacity(1_000)
.withOverflow('drop-new')
.withDeadLetterDrops(true);
const commandOptions = ActorOptions.create()
.withMailbox(() => new BoundedMailbox(commandMailbox));

PriorityMailboxOptions hat denselben Schalter, und dort lohnt er sich öfter: Eine Nachricht, die diese Mailbox abwirft, hat deine Prioritätsfunktion als letzte eingestuft — und nur die Nutzlast kann bestätigen, dass das richtig war.

Standardmäßig aus, und das ist keine Zaghaftigkeit. Ein Drop passiert auf dem Stack des Senders, und ein Dead Letter ist eine dauerhafte Erfassung mit anschließender synchroner Veröffentlichung an jeden Event-Stream-Abonnenten — eine dauerhaft eingeschaltete Variante würde Load Shedding also genau in dem Moment in Arbeit pro Nachricht verwandeln, in dem die Schranke die Dinge billiger machen soll. Als Faustregel: Schalte ihn dort ein, wo du den Verlust hinterher erklären müsstest, und lass ihn für den Feuerwehrschlauch aus, den du bewusst begrenzt hast.

Der Letter trägt Nachricht, Sender und Empfänger — dieselben drei Felder, die jeder andere Verlustpfad im Framework festhält — und in attribution den MDC-Kontext sowie den Tracing-Span, die auf dem Envelope mitreisten. Eine begrenzte Mailbox ist der einzige Verlustpfad, der das ganze Envelope in dem Moment noch in der Hand hält, in dem er es aufgibt; genau das lässt sie die Frage beantworten, die der Zähler nicht beantworten kann: nicht, dass etwas abgeworfen wurde, sondern welche Anfrage es verloren hat. Siehe Dead Letters für die Form — und dafür, warum ein erfasster Eintrag sie bewusst nicht behält.

Eines ändert er nicht: Er erreicht nur Mailboxen, die du selbst konstruierst — withMailboxCapacity hat keine Tür dorthin.

PolicyWann
rejectBackpressure schlägt zum Sender durch. Der Sender muss handeln.
drop-headTelemetrie / Metriken — Neueste gewinnt.
drop-newKritische Arbeit — Eingereihtes behalten, Eingehendes droppen.

Wähle nach der richtigen Antwort auf Overflow:

  • “Sender soll retryen / alerten” → reject.
  • “Veraltete Daten sind falsch” → drop-head.
  • “Eingereihte Arbeit ist wertvoll” → drop-new.

Es gibt kein “Bestes” — kontextabhängig.

Für Actors mit gemischter Dringlichkeit:

import { ActorOptions, PriorityMailbox } from 'actor-ts';
const workerOptions = ActorOptions.create<Message>()
.withMailbox(() => new PriorityMailbox<Message>({
priorityFor: (m) => m.kind === 'urgent' ? 0 : 5,
}));
const worker = system.spawnAnonymous(Worker, workerOptions);

Niedrigere Zahlen = höhere Priorität. System-Nachrichten übertrumpfen immer.

Nutze für:

  • HTTP-Antworten (dringend) vs Batch-Jobs (aufschiebbar).
  • Health-Pings vs Bulk-Metriken.

Ordnung und eine Obergrenze sind kein Entweder-oder. withMailbox und withMailboxCapacity lassen sich nicht kombinieren, die Capacity liegt also auf den Options der Mailbox selbst:

import { ActorOptions, PriorityMailbox, PriorityMailboxOptions } from 'actor-ts';
const triageOptions = PriorityMailboxOptions.create<Message>()
.withPriorityFor((m) => m.kind === 'urgent' ? 0 : 5)
.withCapacity(10_000)
.withOverflow('drop-lowest-priority');
const workerOptions = ActorOptions.create<Message>()
.withMailbox(() => new PriorityMailbox<Message>(triageOptions));

Die Policy-Menge ist 'drop-lowest-priority' / 'drop-new' / 'reject', per Default reject. drop-head fehlt mit Absicht: der Kopf einer Priority-Queue ist die Nachricht, die du als wichtigste bezeichnet hast. drop-lowest-priority wirft stattdessen vom anderen Ende ab — das ist die Variante von “Last abwerfen”, für die eine Priority-Mailbox überhaupt existiert: die dringende Schicht überlebt, die Bulk-Schicht zahlt.

Drops landen wie alle anderen in actor_mailbox_dropped_total, dasselbe Alerting gilt also weiter.

Eine Form, auf die du beim Dimensionieren achten solltest: eine Nachricht, deren priorityFor nicht auswertbar ist, wird zuletzt rangiert — auf einer vollen Mailbox ist sie damit diejenige, die abgeworfen wird. Das ist die richtige Antwort, bedeutet aber, dass sich ein defekter Priority-Callback hier als steigendes drop-new zeigt und nicht als Fehler — verdrahte onPriorityError, wenn du beides unterscheiden willst.

Siehe Mailboxes für die volle PriorityMailbox-Oberfläche.

producer → reject Backpressure → Sender verlangsamt sich
producer → drop-head → Producer macht weiter; Reader sieht das Neueste
producer → drop-new → Producer macht weiter; Reader verarbeitet das Älteste

Bounded Mailboxes sind eine Ebene in einer Backpressure-Story. Für Ende-zu-Ende-Backpressure (das vorgelagerte System wird langsamer) kombinierst du:

  • Bounded Mailbox am Actor.
  • Sender-Retry-Logik.
  • Upstream-Rate-Limiting (HTTP 429, Broker-Pushback).

Die Mailbox erzwingt die lokale Grenze; der Rest ist dein Protokoll-Design.