Actors/Packages/OpenTelemetry
@sigx/actors-otel · Preview

OpenTelemetry#

Turns the host's own metrics into something your monitoring stack already speaks — without making OpenTelemetry a dependency of anything that does not want it.

v0.1.0 MIT

Installation#

Terminal 
pnpm add @sigx/actors-otel

@opentelemetry/api ≥ 1.9 is an optional peer dependency — the /prometheus entry imports no OpenTelemetry at all.

Two entries, deliberately#

@sigx/actors-otel/prometheus — prometheusOps() and renderPrometheus(). Zero OTel. If you scrape, this is all you need.

@sigx/actors-otel — otelTraces() and otelMetricsBridge(). For OTLP stacks.

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

app.use(metrics()).use(prometheusOps({ secret: process.env.SIGX_OPS_SECRET }));

Mounts GET /_sigx/metrics beside ops(), with the same bearer posture. The secret is mandatory outside dev.

Traces#

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

One CLIENT span per dispatch and one SERVER span per turn, joined across hosts by the W3C traceparent the runtime propagates — captured from the public endpoint header and carried on the cluster envelope.

With no tracer provider registered the plugin is inert and costs nothing.

The cardinality rule#

Labels are type and method — never actor keys. An actor key is unbounded by construction, and a key-labelled metric will take your Prometheus down. This is enforced, not advisory.

Span attributes use a key hash for the same reason the routing token does — and with the same caveat that a hash is log hygiene, not privacy.

Next steps#