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