Initial Commit

packages/api-stack/api/api-sandbox-wasm/src/otel/otel.md

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