first commit

docs/foundation/data/web-workers/src/observability/observability.md

@@ -0,0 +1,100 @@
+# `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).