Skip to main content

Observability

@ovok/native uses the vendor-neutral OpenTelemetry API for traces, metrics, events, and logs. It does not bundle an exporter or require a telemetry vendor.

Exports​

The public telemetry exports include configureOvokTelemetry, sanitizeOvokTelemetryAttributes, startOvokSpan, recordOvokMetric, recordOvokDuration, addOvokSpanEvent, emitOvokLog, and withOvokSpan. They are re-exported from @ovok/native/helpers and the root package. The same barrel exports configureOvokLogger and ovokLogger for a simple application logger. slog is the separate legacy structured-logging helper; the internal Sentry-named alias is not a public Sentry integration.

Global providers​

Register the application's OpenTelemetry providers before mounting the SDK. The SDK uses the global providers automatically when the corresponding optional OpenTelemetry packages are installed.

import { configureOvokTelemetry } from "@ovok/native";

// Optional: useful when the app owns providers that are not registered globally.
configureOvokTelemetry({
  tracerProvider,
  meterProvider,
  loggerProvider,
});

The explicit providers use the standard OpenTelemetry getTracer, getMeter, and getLogger contracts, so the app can supply its own SigNoz, Datadog, or other exporter setup.

Instrumented operations​

The SDK emits telemetry for Bluetooth scans, device discovery, connection and pairing, status changes, readings, background-queue delivery and retries, health imports, and save timing. Background execution is not guaranteed to emit telemetry because the host and operating system own those lifecycles. Error counters use a supplied error code when one is available; automatic span failures may use the JavaScript error name.

Attributes are deliberately limited to operational context such as device model, measurement type, platform, retry count, and provider. Measurement values, patient identifiers, and raw device payloads are never sent as telemetry attributes.

Apps that do not install OpenTelemetry continue to work with the normal SDK console logger and no telemetry exporter. The SDK does not promise that every background path emits a span or metric; treat telemetry as best-effort diagnostics.