instrument

@rotorsoft/act-root

---

@rotorsoft/act-root / act-otel / instrument

Function: instrument()

instrument(app, options?): Disposer

Defined in: libs/act-otel/src/index.ts:139

Subscribe to a built Act's lifecycle events and maintain the canonical Prometheus metric set:

Metric	Type	Labels	Source event
act_events_committed_total	counter	name	committed
act_reactions_acked_total	counter	lane	acked
act_reactions_blocked_total	counter	lane	blocked
act_settled_total	counter	—	settled
act_streams_closed_total	counter	—	closed
act_events_forgotten_total	counter	—	forgotten
act_notifications_total	counter	—	notified
act_errors_total	counter	circuit	error
act_streams_blocked	gauge	—	blocked_streams() per scrape

Label cardinality is bounded by design: event names come from the registry, lanes are declared at build, circuit states are three. There is deliberately no per-stream label — stream ids are unbounded and would blow up a Prometheus instance.

The alerting split from the observability guide applies: a non-zero act_streams_blocked and act_errors_total{circuit="open"} growth are page-worthy; the rest are dashboard material.

Returns a Disposer that unsubscribes the listeners and removes the metrics from the registry — hand it to Act's dispose(...) registry so Ctrl-C tears the bridge down with everything else:

Parameters

app

ActSurface

A built Act orchestrator

options?

InstrumentOptions = {}

See InstrumentOptions

Returns

Disposer

Disposer that detaches listeners and unregisters the metrics

Example

import { act, dispose } from "@rotorsoft/act";
import { instrument } from "@rotorsoft/act-otel";
import { register } from "prom-client";

const app = act().withState(Task).build();
dispose(instrument(app));

// serve the scrape endpoint on your HTTP surface
root.get("/metrics", async (c) => c.text(await register.metrics()));

Throws

ZodError when options are out of range (misconfiguration surfaces at startup, not on the first scrape)