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