# instruments

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

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

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

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

## Usage: Advanced

```ts
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).