72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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.
|