@open-infra/telemetry-browser

Consent-aware browser traces, logs, and metrics using official OpenTelemetry providers. Includes bounded offline trace replay and privacy filtering.

Install

npm install @open-infra/telemetry-browser

Use a browser bundler. Start only after window and document exist. React and Vue bindings are separate packages: @open-infra/telemetry-browser-react and @open-infra/telemetry-browser-vue.

Configure a server-controlled gateway

import { createBrowserTelemetry } from '@open-infra/telemetry-browser';

const telemetry = createBrowserTelemetry({
  serviceName: 'storefront',
  projectId: 'commerce',
  consent: 'unknown',
  exporter: {
    traceEndpoint: '/v1/traces',
    logEndpoint: '/v1/logs',
    metricEndpoint: '/v1/metrics',
  },
});
await telemetry.start();

// Invoke after the user grants your application's telemetry consent.
await telemetry.setConsent('granted');
telemetry.logger.info('checkout.started');
telemetry.telemetryMetrics.counter('checkout.started');

Your server must route these endpoints to an OTLP/HTTP protobuf receiver. It should authenticate the session, enforce origin/rate/size limits, and attach backend credentials. Never put privileged exporter keys in browser JavaScript. Cross-origin exporters require exporter.allowedOrigins and compatible CORS/CSP configuration.

Consent and persistence

Collection starts only with granted consent. denied clears queued offline traces and permits a later grant. revoked clears data and is terminal for the controller. Every grant starts a new collection epoch.

Offline traces use bounded IndexedDB storage by default; set offline: { enabled: false } to disable it. Logs and metrics remain memory-only. Replayed traces retain original timestamps and carry telemetry.replayed=true. Delivery is at least once; duplicates and losses are possible. Browser storage availability and eviction are outside the SDK's control.

Runtime lifecycle

Create one global runtime per page. Call forceFlush() when necessary and shutdown() for explicit teardown. Shutdown does not allow another global runtime to replace it; reload the page. registerGlobal: false supports isolated tests with explicitly supplied providers.

Fetch, XHR, page loading, errors, navigation, and web vitals are enabled by default; interaction capture is opt-in. Review policy, instrumentation, queue limits, and sampling for your application. Never use user/session/request IDs as metric dimensions.

Operations · Delivery semantics

Apache-2.0.