first commit

docs/api-stack/api/api-plugin-event-bus/src/otel/instruments.md

@@ -0,0 +1,100 @@
+# `instruments.ts` — OTel instrument bundle for the event-bus plugin
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Exposes the five OpenTelemetry instruments emitted from the plugin's
+production paths and a lazy singleton (`getEventBusInstruments()`) plus
+matching reset helper. The lazy binding lets the plugin record metrics
+against the application's globally-installed `MeterProvider`, while the
+reset helper gives test setup a clean slate when it installs a fresh
+in-memory `MeterProvider` before each run.
+
+## Features
+
+- 3 counters, 1 up/down counter, 1 histogram.
+- Lazily resolved meter; bound on first call to
+  `getEventBusInstruments()`.
+- `resetEventBusInstruments()` flushes the cached bundle so the next
+  call rebinds against the current `MeterProvider`.
+
+## Usage: Basic
+
+```ts
+import { getEventBusInstruments } from "@suaveplan/api-plugin-event-bus/otel/instruments";
+
+const instruments = getEventBusInstruments();
+instruments.publishedTotal.add(1, {
+    outcome: "success",
+    topic_root: "order",
+});
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    AggregationTemporality,
+    InMemoryMetricExporter,
+    MeterProvider,
+    PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+import { metrics } from "@opentelemetry/api";
+import {
+    getEventBusInstruments,
+    resetEventBusInstruments,
+} from "@suaveplan/api-plugin-event-bus/otel/instruments";
+
+const exporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+metrics.setGlobalMeterProvider(
+    new MeterProvider({
+        readers: [
+            new PeriodicExportingMetricReader({
+                exporter,
+                exportIntervalMillis: 60_000,
+            }),
+        ],
+    })
+);
+resetEventBusInstruments();
+const instruments = getEventBusInstruments();
+instruments.subscriptionsActive.add(1);
+```
+
+## API Reference
+
+### `getEventBusInstruments(): EventBusInstruments`
+
+Returns the cached bundle, building it on first call. Subsequent calls
+return the same object — never call `getMeter()` directly so test code
+can swap providers via `resetEventBusInstruments`.
+
+### `resetEventBusInstruments(): void`
+
+Discards the cached bundle. Call from test setup after installing a
+fresh `MeterProvider`.
+
+### `interface EventBusInstruments`
+
+- `publishedTotal: Counter` — `event_bus.published_total{outcome,topic_root}`.
+- `droppedTotal: Counter` — `event_bus.dropped_total{policy}`.
+- `duplicatesTotal: Counter` — `event_bus.duplicates_total`.
+- `subscriptionsActive: UpDownCounter` — `event_bus.subscriptions_active`.
+- `publishDurationMs: Histogram` — `event_bus.publish_duration_ms`.
+
+## Implementation Notes
+
+- The meter name (`@suaveplan/api-plugin-event-bus`) matches the npm
+  package name — operators filter by `meter.name` in their pipelines.
+- The histogram does not set explicit boundaries; the SDK default
+  buckets (1ms–10s) cover the expected publish range. Operators tuning
+  for high-throughput buses should configure a `View` on the meter
+  provider.
+- `subscriptionsActive` is an `UpDownCounter` rather than a gauge so
+  the value is correct under multi-process Prometheus scraping with
+  delta temporality.
+- Cached singleton avoids re-creating instruments on every request —
+  meter instances are not pooled internally by `@opentelemetry/api`.