1/**
2 * Standard metric definitions used by the unstable cluster runtime. The gauges
3 * track runner-local entities, singleton processes, registered runners,
4 * healthy runners, and acquired shards.
5 *
6 * This module only defines the metric handles. The runtime components that
7 * manage entities, runners, singletons, and sharding update these gauges while
8 * the cluster is running.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13import * as Metric from "../Metric.ts"
14
15/**
16 * Creates a gauge tracking the number of active entity instances for each entity type on
17 * the current runner.
18 *
19 * **When to use**
20 *
21 * Use when instrumenting runner-local entity counts and tagging them by entity
22 * type for cluster dashboards.
23 *
24 * **Details**
25 *
26 * Bigint gauge named `effect_cluster_entities`, updated with the entity type as
27 * a metric tag.
28 *
29 * **Gotchas**
30 *
31 * This gauge is runner-local and sampled by the entity manager loop. Aggregate
32 * across runners and expect up to roughly one polling interval of lag.
33 *
34 * @see {@link singletons} for singleton process counts on the current runner
35 * @see {@link shards} for shard ownership on the current runner
36 *
37 * @stability unstable
38 * @category metrics
39 * @since 4.0.0
40 */
41export const entities = Metric.gauge("effect_cluster_entities", { bigint: true })
42
43/**
44 * Creates a gauge tracking the number of singleton processes currently running on the
45 * current runner.
46 *
47 * @stability unstable
48 * @category metrics
49 * @since 4.0.0
50 */
51export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: true })
52
53/**
54 * Represents a gauge tracking the number of registered cluster runners.
55 *
56 * **When to use**
57 *
58 * Use to monitor the registered runners currently known to the cluster runtime.
59 *
60 * **Gotchas**
61 *
62 * The value can lag briefly during membership changes or failure detection.
63 *
64 * @see {@link runnersHealthy} for the healthy-runner subset
65 *
66 * @stability unstable
67 * @category metrics
68 * @since 4.0.0
69 */
70export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
71
72/**
73 * Represents a gauge tracking the number of cluster runners currently considered healthy.
74 *
75 * **When to use**
76 *
77 * Use to monitor the healthy subset of registered cluster runners.
78 *
79 * **Details**
80 *
81 * Bigint gauge named `effect_cluster_runners_healthy`.
82 *
83 * **Gotchas**
84 *
85 * The value reflects the runtime's health-check view and can lag during
86 * membership changes or failure detection.
87 *
88 * @see {@link runners} for the total registered-runner gauge
89 *
90 * @stability unstable
91 * @category metrics
92 * @since 4.0.0
93 */
94export const runnersHealthy = Metric.gauge("effect_cluster_runners_healthy", { bigint: true })
95
96/**
97 * Represents a gauge tracking the number of shards currently acquired by the current runner.
98 *
99 * **When to use**
100 *
101 * Use to observe shard ownership held by the current runner during startup,
102 * rebalancing, or failover.
103 *
104 * **Details**
105 *
106 * Bigint gauge named `effect_cluster_shards`, updated from the sharding
107 * acquisition loop using the current acquired shard count.
108 *
109 * **Gotchas**
110 *
111 * This is runner-local, not a cluster-wide shard total. Aggregate per-runner
112 * values carefully.
113 *
114 * @stability unstable
115 * @category metrics
116 * @since 4.0.0
117 */
118export const shards = Metric.gauge("effect_cluster_shards", { bigint: true })