`telemetry`

(no submodules)

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

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

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

Usage: Advanced

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.

2.7 KiB Raw Blame History

telemetry