first commit

docs/ui/react/react-control-surface/src/telemetry/telemetry.md

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