Installation#

Mount it beside ops(), give it the same secret, and point your scraper at it.

Install#

pnpm add @sigx/actors-otel
# only if you want traces or the OTLP bridge:
pnpm add @opentelemetry/api

npm install @sigx/actors-otel
# only if you want traces or the OTLP bridge:
npm install @opentelemetry/api

yarn add @sigx/actors-otel
# only if you want traces or the OTLP bridge:
yarn add @opentelemetry/api

bun add @sigx/actors-otel
# only if you want traces or the OTLP bridge:
bun add @opentelemetry/api

Prometheus#

import { metrics } from '@sigx/actors/host';
import { prometheusOps } from '@sigx/actors-otel/prometheus';

export const app = defineActorApp({ actors, storage })
    .use(metrics())
    .use(prometheusOps({ secret: process.env.SIGX_OPS_SECRET }));

metrics() must be enabled for there to be anything to export — if you run metrics({ enabled: false }) in production, the endpoint reports zeroes until you enable it.

scrape_configs:
  - job_name: sigx-actors
    metrics_path: /_sigx/metrics
    authorization:
      credentials_file: /etc/prometheus/sigx-ops-secret
    static_configs:
      - targets: ['actors-host:7311']

Options#

The default bucket grid runs from 1µs to about 134s in roughly 28 per-octave bounds — wide enough to cover a sub-millisecond local dispatch and a multi-second turn in the same histogram.

Two caveats#

metrics().reset() breaks monotonicity. Prometheus counters are expected only ever to increase, so a reset() looks like a counter restart. That is survivable — rate() handles restarts — but do not wire reset() to anything periodic.

Never label by actor key. Enforced by the package, but worth knowing why: keys are unbounded, and one high-cardinality label is enough to take a Prometheus down.

Traces and the bridge#

import { otelMetricsBridge, otelTraces } from '@sigx/actors-otel';

app.use(otelTraces({ turnSpans: true }))
   .use(otelMetricsBridge({ percentileGauges: true }));

Both are inert with no provider registered. turnSpans: false keeps the CLIENT spans and drops the per-turn SERVER spans, which is the cheaper configuration if you only want the call graph.

Verify#

curl -H "authorization: Bearer $SIGX_OPS_SECRET" http://localhost:7311/_sigx/metrics | head

Next steps#

• API reference — exports.
• Observability — choosing an approach.
• Metrics — what is being exported.