# `telemetry`

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

## Purpose

The `telemetry` module is the single owner of every OpenTelemetry instrument
emitted by `@suaveplan/react-control-surface`. Centralising instrument
creation here keeps the meter name (`@suaveplan/react-control-surface`)
consistent across both the foundation chunk and the runtime chunk that lands
later, so dashboards built early never need to be re-keyed.

Two instruments are created at module load: the `control_surface_interactions_total`
counter (one increment per user-driven `onChange`) and the
`control_surface_render_duration_ms` histogram (one observation per
`<Surface>` render commit). Both are wired into the global `metrics`
provider; consumers attaching an in-memory provider for tests automatically
see both instruments.

## Features

- Stable meter name `@suaveplan/react-control-surface`.
- Counter `control_surface_interactions_total` tagged `{kind}`.
- Histogram `control_surface_render_duration_ms` in milliseconds.
- Convenience helpers `recordInteraction(kind)` and `recordRenderDuration(ms)`.

## Usage: Basic

```ts
import { recordInteraction } from "@suaveplan/react-control-surface/telemetry";

function onPress(): void {
    recordInteraction("button-momentary");
}
```

## Usage: Advanced

```ts
import { metrics } from "@opentelemetry/api";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import {
    controlSurfaceInteractionsCounter,
    recordInteraction,
} from "@suaveplan/react-control-surface/telemetry";

const provider = new MeterProvider();
metrics.setGlobalMeterProvider(provider);

// Drive a few interactions then export a snapshot in a test:
recordInteraction("switch-2");
recordInteraction("switch-2");
void controlSurfaceInteractionsCounter.add(1, { kind: "led" });
```

## API Reference

- `controlSurfaceInteractionsCounter: Counter` — base instrument.
- `controlSurfaceRenderDurationHistogram: Histogram` — base instrument.
- `recordInteraction(kind: string): void` — increments the counter by one
  with the `kind` attribute.
- `recordRenderDuration(durationMs: number): void` — records a single
  observation on the histogram.

## Implementation Notes

Instruments are created exactly once per process via the module-static
`METER` constant. The OTel SDK is intentionally not initialised by this
module — application code (or tests) owns wiring `MeterProvider`. When no
provider is set the OTel default no-op provider absorbs every call cheaply,
so wrapping calls in `if (devMode)` is unnecessary. Histograms accept any
finite number; callers are responsible for converting their measurement
into milliseconds before invoking `recordRenderDuration`.