Stock metrics

When the metrics extension is enabled, the framework automatically records a baseline of metrics covering the actor lifecycle, message handling, bounded mailboxes, and the cluster.

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

const metrics = system.extension(MetricsExtensionId).enable();
// Stock metrics now record into the live registry — no further setup

These are the metrics you’d write yourself anyway. Shipping them out of the box lets you wire a dashboard immediately.

Actor metrics

Actor-lifecycle and message-handling metrics, recorded across the whole system — each is a single unlabeled series:

Metric	Type	Labels	Meaning
actor_created_total	counter	—	Actors successfully started.
actor_terminated_total	counter	—	Actors stopped (clean stop or post-failure).
actor_restarted_total	counter	—	Supervisor-driven restarts.
actor_messages_delivered_total	counter	—	User messages delivered to onReceive.
actor_message_handler_seconds	histogram	—	Time spent inside onReceive handlers, in seconds.

actor_message_handler_seconds uses the default seconds-scale buckets; its p99 is your “how slow is a handler” signal.

Mailbox metrics

Metric	Type	Labels	Meaning
actor_mailbox_size	gauge	class, path	Queued user messages, sampled. Only actors at or above 10 000 are represented.
actor_mailbox_dropped_total	counter	class, path, reason	Messages dropped by a bounded mailbox’s overflow policy.

actor_mailbox_size is the backlog signal. Mailboxes are unbounded by default, so an actor that falls behind accumulates rather than sheds — and a series only exists once one crosses 10 000 queued messages. Its presence is therefore the alert: on a healthy system the metric is empty. A mailbox that drains back below the floor reads 0 rather than its last spike, and the same threshold produces a log warning (repeated at each doubling) whether or not metrics are on.

actor_mailbox_dropped_total is the shedding signal, and only appears for actors whose mailbox discards something — which, since the default is unbounded, means actors someone deliberately bounded. The reason label records the policy that fired (drop-head / drop-new). Both ways of bounding are covered: withMailboxCapacity, and a mailbox you build yourself and pass to withMailbox.

Cluster metrics

Metric	Type	Labels	Meaning
cluster_members_up	gauge	—	Members currently in the up state (this node’s view).
cluster_gossip_rounds_total	counter	—	Gossip-push rounds initiated by this node.
cluster_gossip_records_refused_total	counter	reason	Gossiped member records a merge-path guard refused.

For monitoring cluster health:

• cluster_members_up should equal your configured replica count; a persistent shortfall means members are down or unreachable.
• cluster_gossip_rounds_total rate confirms gossip is flowing — a flat line means this node has stopped gossiping.
• cluster_gossip_records_refused_total should sit at zero. Movement on reason="version-skew" means gossiped versions are further ahead of this node’s clock than maxVersionSkewMs — either a peer’s clock has drifted or someone is trying to pre-claim an address. Movement on reason="map-cap" means max-members / max-tombstones is full. The counter is incremented once per frame with that frame’s count, and the label set is closed at those two values.

DistributedData metrics

The CRDT replicator’s quorum path — updateAsync / getAsync — and its wire decoder. Every label set here is fixed and tiny, so the four families contribute six series in total:

Metric	Type	Labels	Meaning
distributed_data_quorum_pending	gauge	—	Quorum reads and writes currently awaiting peer replies on this replica.
distributed_data_quorum_timeouts_total	counter	operation	Quorum requests that hit their deadline before enough replicas replied.
distributed_data_quorum_rejected_total	counter	operation	Quorum requests refused because max-pending-quorum-requests was reached.
distributed_data_dropped_values_total	counter	—	Peer-supplied CRDT values this replica refused to decode.

operation is write or read — those two values and no others.

• distributed_data_quorum_pending riding near your configured max-pending-quorum-requests means the next caller is about to be refused; either peers have stopped acking or the cap is too low for the workload.
• distributed_data_quorum_rejected_total and ..._timeouts_total separate the two failure shapes: refused means the request never started, timed out means it started and nobody answered in time. See Quorum reads and writes.
• distributed_data_dropped_values_total is not a tuning signal at all — a peer is sending payloads this replica cannot decode, which means a broken or hostile node.

Overhead

There is no opt-out flag — stock metrics are always wired into the framework. Until you call .enable(), every instrumentation call resolves against a noop registry (a single object lookup that records nothing), so the cost is negligible. Enabling the extension swaps in the live registry and the same calls start capturing.

High-cardinality `path` label

// Per-sharded-entity actor: thousands of distinct paths
actor_mailbox_dropped_total{path="actor-ts://.../entity-1"}
actor_mailbox_dropped_total{path="actor-ts://.../entity-2"}
...

actor_mailbox_dropped_total carries a path label, which can be high-cardinality for sharded entities (one path per actor). The series count is bounded but not small: the registry’s cardinality cap stops the family at 10 000 series and folds the rest into path="__overflow__", so the process cannot be memory-exhausted through this label — but 10 000 series in one family is still a lot to scrape. Re-aggregate or drop the label downstream if you run enough entities to approach that, and treat the appearance of an __overflow__ series as the signal that you have.

Counters reset on restart

// After a pod restart, actor_messages_delivered_total starts at 0 again

Counters are per-process. Prometheus understands this (computes rates over the increasing series; handles resets gracefully). But raw counter values aren’t meaningful across restarts.

Where to next

• Observability overview — the bigger picture.
• Core metrics — for your own custom metrics.
• Prometheus exporter — how to scrape these.
• Management overview — for the /metrics endpoint.