# otel

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

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

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

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

## Usage: Advanced

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