API reference#

Exports of @sigx/actors-otel v0.11.0.

@sigx/actors-otel/prometheus#

Imports no OpenTelemetry.

prometheusOps(options?)#

An ActorPlugin mounting the scrape endpoint.

interface PrometheusOpsOptions extends Omit<RenderPrometheusOptions, 'sockets' | 'cluster'> {
    path?: string;              // '/_sigx/metrics'
    secret?: string;            // mandatory outside dev
    cluster?: () => Partial<ClusterCounterTotals> | undefined;   // read on every scrape
}
interface RenderPrometheusOptions {
    prefix?: string;            // 'sigx_actors_'
    bucketsSeconds?: number[];  // per-octave grid, 1µs → ~134s
    sockets?: SocketStatsDigest | null;
    cluster?: Partial<ClusterCounterTotals> | null;
}

prometheusOps reads the socket digest off the registry itself — publish it with registry.reportDigest('sockets', () => stats.digest()) — and the cluster counters through the cluster thunk, typically () => plugin.placement.counters() where plugin is the cluster() plugin. The thunk may answer undefined until placement is up.

renderPrometheus(digest, stats, options)#

The pure function underneath — no plugin, no route. Use it to serve the exposition yourself. options.sockets and options.cluster take the digest and the totals directly; absent or null, the matching family is not emitted at all.

SocketStatsDigest — the shape socketStats().digest() returns — is exported as a type.

Optional families#

The full socket list is on Observability.

@sigx/actors-otel#

otelTraces(options?)#

interface OtelTracesOptions {
    tracerProvider?: TracerProvider;
    turnSpans?: boolean;   // true
}

One CLIENT span per dispatch, one SERVER span per turn. Cross-host joins ride the runtime's W3C traceparent.

otelMetricsBridge(options?)#

interface OtelMetricsBridgeOptions {
    meterProvider?: MeterProvider;
    percentileGauges?: boolean;   // true
    cluster?: () => Partial<ClusterCounterTotals> | undefined;
}

Beside the call metrics it observes sigx.actors.socket.* — the Prometheus socket set, plus sigx.actors.socket.connection_duration.p50 / .p90 / .p99 under percentileGauges — when the app publishes a sockets digest, and sigx.actors.cluster.dispatches with a locality attribute (local / remote) when cluster answers.

traceparent helpers#

formatTraceparent(fields), parseTraceparent(header), and the TraceparentFields type.

Core plumbing this rides on#

Exported from @sigx/actors and @sigx/actors/host rather than here, but relevant:

• ActorCallContext.traceparent
• the trailing call parameter on ActorTurnObserver
• bucketUpperBoundsUs() and timingSafeEquals from @sigx/actors/host

Labels#

type and method only. Never actor keys — enforced, because keys are unbounded and one high-cardinality label is enough to take a Prometheus down.

Next steps#

• Overview — the two entries.
• Installation — scrape config and caveats.
• Observability — the guide.