instruments

(no submodules)

Purpose

This module owns the OTel instrument bundle the bridge emits. Splitting the bundle off the bridge module makes the metric names a single source of truth (no fan-out of meter.createCounter(...) calls across the package) and gives the conformance harness a reset… entry point to clear cached instruments between scenarios.

The bundle is built lazily and cached so the first bridge invocation takes the meter-binding cost; every subsequent call reuses the instrument handles. Tests that need a clean slate per scenario call the reset helper in their beforeEach.

Features

Four instruments — requestsMarshalledTotal, marshalFailuresTotal, handlerRejectionsTotal, bridgeInvocationDurationMs.
Stable metric names — all four namespaced under sandbox_vm_bridge.* so dashboards can filter the bridge's metrics separately from the underlying sandbox host's metrics.
Lazy binding — meter creation is deferred until first use, so a consumer that imports the module without ever invoking the bridge pays no OTel cost.
Test-friendly reset — resetSandboxVmBridgeInstruments() drops the cached bundle so the next getSandboxVmBridgeInstruments() call re-binds against a freshly-installed MeterProvider.

Usage: Basic

import { getSandboxVmBridgeInstruments } from "@suaveplan/api-sandbox-vm-host-bridge/instruments/instruments";

getSandboxVmBridgeInstruments().requestsMarshalledTotal.add(1, {
    plugin: "demo",
    route: "/foo",
    method: "GET",
});

Usage: Advanced

import {
    getSandboxVmBridgeInstruments,
    resetSandboxVmBridgeInstruments,
} from "@suaveplan/api-sandbox-vm-host-bridge/instruments/instruments";

beforeEach(() => {
    resetSandboxVmBridgeInstruments();
    // ...install a fresh OTel MeterProvider here so the next
    // `getSandboxVmBridgeInstruments()` re-binds against it.
});

afterEach(() => {
    const instruments = getSandboxVmBridgeInstruments();
    // assert against your provider's exported reader
});

API Reference

interface SandboxVmBridgeInstruments — four instrument fields documented above.
getSandboxVmBridgeInstruments(): SandboxVmBridgeInstruments — lazy, cached.
resetSandboxVmBridgeInstruments(): void — drops the cached bundle.

Implementation Notes

The Counter and Histogram types come from @opentelemetry/api directly rather than from any of the @opentelemetry/sdk-* packages so this module stays SDK-agnostic — the consumer's choice of metric exporter is honoured because the API package looks up the bound MeterProvider on each metrics.getMeter() call. The cache is module-local so an HMR reload in development never strands a stale bundle (the module reloads, the cache resets implicitly).

2.8 KiB Raw Blame History