`instruments`

(no submodules)

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

import { createSseBunInstruments } from "@suaveplan/api-sse-bun";

const instruments = createSseBunInstruments({
    connectionSnapshot: () => [],
});
instruments.eventsSentTotal.add(1, { plugin: "demo", topic: "audit" });

Usage: Advanced

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.

2.9 KiB Raw Blame History

instruments