first commit

docs/api-stack/api/api-sandbox-vm-host-bridge/src/instruments/instruments.md

@@ -0,0 +1,84 @@
+# 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).