Stock-Metriken

Wenn die Metrics-Extension aktiviert ist, zeichnet das Framework automatisch eine Basislinie an Metriken auf, die den Actor-Lebenszyklus, die Nachrichtenverarbeitung, beschränkte Mailboxen und den Cluster abdecken.

import { ActorSystem, MetricsExtensionId } from 'actor-ts';

const metrics = system.extension(MetricsExtensionId).enable();
// Stock-Metriken zeichnen jetzt in die Live-Registry auf — kein weiteres Setup

Das sind die Metriken, die du dir sonst selbst schreiben würdest. Sie Out-of-the-Box auszuliefern erlaubt dir, sofort ein Dashboard zu verdrahten.

Actor-Metriken

Metriken für Actor-Lebenszyklus und Nachrichtenverarbeitung, systemweit aufgezeichnet — jede ist eine einzelne Serie ohne Labels:

Metrik	Typ	Labels	Bedeutung
`actor_created_total`	counter	—	Erfolgreich gestartete Actor.
`actor_terminated_total`	counter	—	Gestoppte Actor (sauberer Stopp oder nach einem Fehler).
`actor_restarted_total`	counter	—	Supervisor-getriebene Restarts.
`actor_messages_delivered_total`	counter	—	An `onReceive` zugestellte User-Nachrichten.
`actor_message_handler_seconds`	histogram	—	Zeit in `onReceive`-Handlern, in Sekunden.

actor_message_handler_seconds nutzt die standardmäßigen Sekunden-Buckets; sein p99 ist dein Signal „wie langsam ist ein Handler”.

Mailbox-Metriken

Metrik	Typ	Labels	Bedeutung
`actor_mailbox_size`	gauge	`class`, `path`	Wartende User-Nachrichten, gesampelt. Nur Actors ab 10 000 sind vertreten.
`actor_mailbox_dropped_total`	counter	`class`, `path`, `reason`	Von der Overflow-Policy einer beschränkten Mailbox verworfene Nachrichten.

actor_mailbox_size ist das Rückstau-Signal. Mailboxes sind per Default unbounded, ein zurückfallender Actor sammelt also an, statt abzuwerfen — und eine Serie entsteht erst, wenn einer 10 000 wartende Nachrichten überschreitet. Ihr Vorhandensein ist damit der Alarm: auf einem gesunden System ist die Metrik leer. Eine Mailbox, die wieder unter die Schwelle fällt, liest 0 statt ihres letzten Ausschlags, und dieselbe Schwelle erzeugt eine Log-Warnung (wiederholt bei jeder Verdopplung), unabhängig davon ob Metriken aktiv sind.

actor_mailbox_dropped_total ist das Abwurf-Signal und taucht nur für Actors auf, deren Mailbox etwas verwirft — da der Default unbounded ist, also für Actors, die jemand bewusst begrenzt hat. Das reason-Label hält die ausgelöste Policy fest (drop-head / drop-new). Beide Wege, zu begrenzen, sind abgedeckt: withMailboxCapacity und eine selbst gebaute Mailbox aus withMailbox.

Cluster-Metriken

Metrik	Typ	Labels	Bedeutung
`cluster_members_up`	gauge	—	Mitglieder aktuell im Zustand `up` (Sicht dieses Knotens).
`cluster_gossip_rounds_total`	counter	—	Von diesem Knoten initiierte Gossip-Push-Runden.
`cluster_gossip_records_refused_total`	counter	`reason`	Von einer Merge-Pfad-Wache abgelehnte gegossipte Member-Records.

Zum Monitoring der Cluster-Gesundheit:

cluster_members_up sollte deiner konfigurierten Replica-Anzahl entsprechen; ein dauerhafter Fehlbetrag heißt, Mitglieder sind down oder unerreichbar.
Die Rate von cluster_gossip_rounds_total bestätigt, dass Gossip fließt — eine flache Linie heißt, dieser Knoten hat aufgehört zu gossippen.
cluster_gossip_records_refused_total sollte bei null liegen. Bewegung auf reason="version-skew" heißt, gegossipte Versionen liegen weiter vor der Uhr dieses Knotens als maxVersionSkewMs — entweder ist die Uhr eines Peers abgedriftet, oder jemand versucht, eine Adresse vorab zu beanspruchen. Bewegung auf reason="map-cap" heißt, max-members / max-tombstones ist voll. Der Zähler wird einmal pro Frame um dessen Anzahl erhöht, und die Label-Menge ist auf diese zwei Werte geschlossen.

DistributedData-Metriken

Der Quorum-Pfad des CRDT-Replikators — updateAsync / getAsync — und sein Wire-Decoder. Jede Label-Menge hier ist fest und winzig, die vier Familien tragen also insgesamt sechs Serien bei:

Metrik	Typ	Labels	Bedeutung
`distributed_data_quorum_pending`	gauge	—	Quorum-Reads und -Writes, die auf dieser Replika gerade auf Peer-Antworten warten.
`distributed_data_quorum_timeouts_total`	counter	`operation`	Quorum-Requests, die ihre Deadline erreichten, bevor genug Replikas antworteten.
`distributed_data_quorum_rejected_total`	counter	`operation`	Quorum-Requests, die abgelehnt wurden, weil `max-pending-quorum-requests` erreicht war.
`distributed_data_dropped_values_total`	counter	—	Von Peers gelieferte CRDT-Werte, die diese Replika nicht dekodieren wollte.

operation ist write oder read — diese beiden Werte und keine anderen.

distributed_data_quorum_pending dicht an deinem konfigurierten max-pending-quorum-requests heißt, dass der nächste Aufrufer gleich abgelehnt wird; entweder haben Peers aufgehört zu acken oder das Cap ist für die Last zu niedrig.
distributed_data_quorum_rejected_total und ..._timeouts_total trennen die beiden Fehlerformen: abgelehnt heißt, der Request hat nie begonnen; Timeout heißt, er hat begonnen und niemand antwortete rechtzeitig. Siehe Quorum-Reads und -Writes.
distributed_data_dropped_values_total ist gar kein Tuning-Signal — ein Peer schickt Payloads, die diese Replika nicht dekodieren kann, also ein kaputter oder feindlicher Knoten.

Overhead

Es gibt kein Opt-out-Flag — Stock-Metriken sind immer im Framework verdrahtet. Bis du .enable() aufrufst, löst jeder Instrumentierungsaufruf gegen eine Noop-Registry auf (ein einzelner Objekt-Lookup, der nichts aufzeichnet), sodass die Kosten vernachlässigbar sind. Das Aktivieren der Extension tauscht die Live-Registry ein und dieselben Aufrufe beginnen aufzuzeichnen.

// Per-sharded-Entity-Actor: Tausende verschiedene Pfade
actor_mailbox_dropped_total{path="actor-ts://.../entity-1"}
actor_mailbox_dropped_total{path="actor-ts://.../entity-2"}
...

actor_mailbox_dropped_total trägt ein path-Label, das für sharded Entities hoch-kardinal sein kann (ein Pfad pro Actor). Die Serien-Anzahl ist beschränkt, aber nicht klein: die Kardinalitätsgrenze der Registry stoppt die Familie bei 10 000 Serien und faltet den Rest in path="__overflow__" — der Prozess lässt sich über dieses Label also nicht mehr speicher-erschöpfen, aber 10 000 Serien in einer Familie sind immer noch viel zum Scrapen. Aggregiere neu oder strippe das Label downstream, wenn du genug Entities betreibst, um dort hinzukommen, und werte das Auftauchen einer __overflow__-Serie als genau dieses Signal.

// Nach einem Pod-Neustart fängt actor_messages_delivered_total wieder bei 0 an

Counter sind per-Prozess. Prometheus versteht das (berechnet Raten über die steigende Serie; behandelt Resets sauber). Aber rohe Counter-Werte sind über Neustarts hinweg nicht aussagekräftig.

Wo es weitergeht

Observability — Überblick — das größere Bild.
Core-Metriken — für deine eigenen Custom-Metriken.
Prometheus-Exporter — wie du diese scrapest.
Management — Überblick — für den /metrics-Endpunkt.