# `observability`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

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

## Usage: Advanced Example

```ts
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).