first commit

docs/api-stack/api/api-sse-bun/src/instruments/instruments.md

@@ -0,0 +1,81 @@
+# `instruments`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `instruments` module wires the engine's OpenTelemetry surface. Every
+metric mandated by design doc §11.7 — connection gauge, events-sent
+counter, handshake-duration histogram, replay-hit/miss counter,
+compression-ratio histogram — is exposed as a typed bundle the engine
+records against at the appropriate seam. The observable gauge takes a
+snapshot callback so the engine never pushes connection counts; the SDK
+pulls them when it scrapes the meter.
+
+## Features
+
+- Single meter scope `@suaveplan/api-sse-bun` so OTel resource detection
+  knows which package emitted each metric.
+- Observable gauge `sse.connections{ plugin, path, tenant }` driven by a
+  pluggable snapshot callback.
+- Counter `sse.events_sent_total{ plugin, topic }` incremented per
+  delivered event.
+- Histogram `sse.handshake.duration_ms` recorded once per accepted
+  handshake.
+- Counter `sse.buffer_replays_total{ hit }` labelled `"hit"` when a
+  replay returned events, `"miss"` on `SSE_BUN_BUFFER_MISS`.
+- Histogram `sse.compression_ratio` recorded at stream close.
+
+## Usage: Basic
+
+```ts
+import { createSseBunInstruments } from "@suaveplan/api-sse-bun";
+
+const instruments = createSseBunInstruments({
+    connectionSnapshot: () => [],
+});
+instruments.eventsSentTotal.add(1, { plugin: "demo", topic: "audit" });
+```
+
+## Usage: Advanced
+
+```ts
+import { createSseBunInstruments } from "@suaveplan/api-sse-bun";
+import type { MeterProvider } from "@opentelemetry/api";
+
+declare const meterProvider: MeterProvider;
+
+const instruments = createSseBunInstruments({
+    meterProvider,
+    connectionSnapshot: () => [
+        { plugin: "demo", path: "/sse/audit", tenant: "acme", value: 12 },
+        { plugin: "demo", path: "/sse/audit", tenant: "globex", value: 3 },
+    ],
+});
+instruments.handshakeDurationMs.record(42, { plugin: "demo" });
+instruments.bufferReplaysTotal.add(1, { hit: "miss" });
+instruments.compressionRatio.record(3.7, { plugin: "demo" });
+```
+
+## API Reference
+
+- `type ConnectionSnapshot = () => readonly { plugin, path, tenant,
+  value }[]`.
+- `interface SseBunInstruments` — frozen bundle: `meter`, `connections`
+  (observable gauge), `eventsSentTotal` (counter),
+  `handshakeDurationMs` (histogram), `bufferReplaysTotal` (counter),
+  `compressionRatio` (histogram).
+- `interface SseBunInstrumentsOptions` — optional `meterProvider`,
+  required `connectionSnapshot`.
+- `function createSseBunInstruments(options): SseBunInstruments`.
+
+## Implementation Notes
+
+The module reads the global `MeterProvider` via `metrics.getMeterProvider()`
+when no provider is supplied — matching every other Suaveplan instruments
+module so tests can wire a `@opentelemetry/sdk-metrics`
+`MeterProvider`-like fake without engine-specific glue. The bundle is
+frozen so accidental reassignment of e.g. `instruments.connections = …`
+fails fast in strict mode.