otel

(no submodules)

Purpose

Owns the WASM sandbox host's OpenTelemetry instrument registry. Every counter the host emits on a production path lives in SAND_WASM_COUNTER_NAMES so a regression that drops one of them surfaces as a typecheck error upstream rather than a silent metric gap. The recordPermissionDenied convenience method increments plugin.permission_denied_total with the canonical {plugin, capability, reason} label set every sandbox host shares per design doc §5.2b.

The meter provider can be supplied explicitly (for tests that need a recording double) or implicitly via the OTel global. The package never installs an SDK — SDK init is operator responsibility.

Features

Pre-created counters at construction time so the first .add() is allocation-free.
Frozen instruments bundle and frozen counters table.
Per-plugin meter namespacing under @suaveplan/api-sandbox-wasm/<pluginName> to keep cardinality bounded on multi-plugin hosts.
Falls back to the OTel global provider when no override is given.

Usage: Basic

import { createSandWasmInstruments } from "@suaveplan/api-sandbox-wasm";

const instruments = createSandWasmInstruments({ pluginName: "checkout" });
instruments.recordPermissionDenied("fetch", "destination_not_allowed");

Usage: Advanced

import { MeterProvider } from "@opentelemetry/sdk-metrics";

const provider = new MeterProvider({ readers: [readerWithPrometheusExport] });
const instruments = createSandWasmInstruments({
    pluginName: "checkout",
    meterProvider: provider,
});

API Reference

createSandWasmInstruments(config): SandWasmInstruments
SAND_WASM_COUNTER_NAMES — canonical counter name list.
SandWasmInstruments.{meter, counters, recordPermissionDenied(capability, reason)}
SandWasmInstrumentsConfig.{pluginName, meterProvider?}

Implementation Notes

The meter name is plugin-scoped so per-plugin meters can be wired to per-plugin processors without cardinality leakage. The base label set on every measurement is {plugin} — additional dimensions are added by the call site (e.g. capability + reason for the denial counter).

plugin.permission_denied_total is the single shared denial metric every sandbox host emits — the canonical label set is documented in the design doc §5.2b and pinned by tests so a future host implementation cannot accidentally diverge.

2.4 KiB Raw Permalink Blame History