`observability`

(no submodules)

Purpose

observability.ts exposes createWebWorkersObservability(), the factory that builds the OpenTelemetry counter + histogram bundle every manager and pool consumes. The bundle is injected at construction time, which means a single OTel meter/tracer pair drives every managed worker, every pool slot, and every RPC in a process.

The package defaults to the no-op providers from @opentelemetry/api so consumers who don't wire telemetry pay zero cost. When telemetry is wired, metrics flow through the consumer's MeterProvider without further code changes on the manager side.

Features

Six counters: messages sent / received, workers created / terminated, restarts, errors.
Three histograms: RPC latency (ms), queue depth, pool active workers.
Single-pass construction: callers receive a { meter, tracer, counters, histograms } bundle and pass it to manager / pool constructors via the observability option.
Pass-through behaviour: a fully-formed bundle on WebWorkersObservabilityOptions.observability short-circuits and returns the same reference so consumers can share a single bundle across multiple manager instances.

Usage: Basic Example

import {
    createWebWorkersObservability,
    WorkerManager,
} from "@suaveplan/web-workers";

const obs = createWebWorkersObservability();
const manager = new WorkerManager({
    factory: defineWorker({ url: WORKER_URL }),
    observability: obs,
});

Usage: Advanced Example

import { metrics } from "@opentelemetry/api";
import {
    createWebWorkersObservability,
    WorkerPool,
} from "@suaveplan/web-workers";

const meter = metrics.getMeter("my-app/render");
const obs = createWebWorkersObservability({ meter });

const renderPool = new WorkerPool(
    { url: RENDER_URL, size: 4, scheduler: "least-busy" },
    {
        factory: defineWorker({ url: RENDER_URL }),
        observability: obs,
    }
);
const audioPool = new WorkerPool(
    { url: AUDIO_URL, size: 2 },
    {
        factory: defineWorker({ url: AUDIO_URL }),
        // share the same bundle so cross-pool metrics aggregate on a single
        // meter
        observability: obs,
    }
);

API Reference

createWebWorkersObservability(opts?: WebWorkersObservabilityOptions): WebWorkersObservability — builds a bundle on the supplied (or no-op) meter / tracer.
WebWorkersObservabilityOptions = { meter?, tracer?, observability? } — every field optional; observability short-circuits.
WebWorkersObservability = { meter, tracer, counters, histograms }.
WebWorkersCounters — messagesSentTotal, messagesReceivedTotal, workersCreatedTotal, workersTerminatedTotal, restartsTotal, errorsTotal.
WebWorkersHistograms — rpcLatencyMs, queueDepth, poolActiveWorkers.

Implementation Notes

Instruments are created via createCounter / createHistogram from @suaveplan/opentelemetry, which guarantees consistent naming + unit conventions across Suaveplan. Counter names use the web_workers_*_total convention (Prometheus-compatible). Histograms use ms-valued buckets for latency and unit-less counts for depth gauges. The tracer field is exposed for consumers who want to wrap spans around manager methods — none of the package's own code currently creates spans since RPC calls would create one span per request which is rarely the right granularity (consumers should span the higher-level operation).

3.5 KiB Raw Blame History

observability