ClusterMetrics.ts
ClusterMetrics.ts overview
Section titled “ClusterMetrics.ts overview”Standard metric definitions used by the unstable cluster runtime. The gauges track runner-local entities, singleton processes, registered runners, healthy runners, and acquired shards.
This module only defines the metric handles. The runtime components that manage entities, runners, singletons, and sharding update these gauges while the cluster is running.
Since v4.0.0
Exports Grouped by Category
Section titled “Exports Grouped by Category”metrics
Section titled “metrics”entities
Section titled “entities”Creates a gauge tracking the number of active entity instances for each entity type on the current runner.
When to use
Use when instrumenting runner-local entity counts and tagging them by entity type for cluster dashboards.
Details
Bigint gauge named effect_cluster_entities, updated with the entity type as
a metric tag.
Gotchas
This gauge is runner-local and sampled by the entity manager loop. Aggregate across runners and expect up to roughly one polling interval of lag.
See
singletonsfor singleton process counts on the current runnershardsfor shard ownership on the current runner
Signature
declare const entities: Metric.Gauge<bigint>Since v4.0.0
runners
Section titled “runners”Represents a gauge tracking the number of registered cluster runners.
When to use
Use to monitor the registered runners currently known to the cluster runtime.
Gotchas
The value can lag briefly during membership changes or failure detection.
See
runnersHealthyfor the healthy-runner subset
Signature
declare const runners: Metric.Gauge<bigint>Since v4.0.0
runnersHealthy
Section titled “runnersHealthy”Represents a gauge tracking the number of cluster runners currently considered healthy.
When to use
Use to monitor the healthy subset of registered cluster runners.
Details
Bigint gauge named effect_cluster_runners_healthy.
Gotchas
The value reflects the runtime’s health-check view and can lag during membership changes or failure detection.
See
runnersfor the total registered-runner gauge
Signature
declare const runnersHealthy: Metric.Gauge<bigint>Since v4.0.0
shards
Section titled “shards”Represents a gauge tracking the number of shards currently acquired by the current runner.
When to use
Use to observe shard ownership held by the current runner during startup, rebalancing, or failover.
Details
Bigint gauge named effect_cluster_shards, updated from the sharding
acquisition loop using the current acquired shard count.
Gotchas
This is runner-local, not a cluster-wide shard total. Aggregate per-runner values carefully.
Signature
declare const shards: Metric.Gauge<bigint>Since v4.0.0
singletons
Section titled “singletons”Creates a gauge tracking the number of singleton processes currently running on the current runner.
Signature
declare const singletons: Metric.Gauge<bigint>Since v4.0.0