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

instruments.ts — OTel instrument bundle for the event-bus plugin

(no submodules)

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

import { getEventBusInstruments } from "@suaveplan/api-plugin-event-bus/otel/instruments";

const instruments = getEventBusInstruments();
instruments.publishedTotal.add(1, {
    outcome: "success",
    topic_root: "order",
});

Usage: Advanced

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.