@ultrvlt/browser-rum

Browser Real User Monitoring SDK for Ultraviolet Observability. Captures Core Web Vitals, JavaScript errors, fetch timing and page views, and ships them as OTLP spans to your Ultraviolet ingest gateway — the same pipeline your backend telemetry already uses. Optional session replay (rrweb) records the DOM with privacy masking on by default.

The headline: every instrumented fetch injects a W3C traceparent header, so a browser request and the backend spans it triggers share one trace_id. A slow page action in the RUM view clicks straight through to its server-side waterfall.

Install

npm (bundled apps)

npm install @ultrvlt/browser-rum

import { init } from '@ultrvlt/browser-rum'

const rum = init({
  endpoint: 'https://gateway.example.com', // ingest gateway base URL
  app: 'storefront-web',                   // becomes service.name
  // optional:
  // siteId: 'us-east-1',
  // ingestKey: '<your site ingest key>',  // if the gateway requires one
  // sessionSampleRate: 0.5,               // 0..1, decided once per session
  // propagateTo: [location.origin, 'https://api.example.com'],
})

// once the signed-in user is known:
rum.setUser('user-123')

Script tag (self-hosted / air-gapped)

If you can't pull from npm — or you'd rather not add the SDK to your build — use the prebuilt IIFE bundle. Host dist/ultrvlt-rum.iife.js on your own origin and load it directly; it exposes a global UltrvltRUM:

<script src="/js/ultrvlt-rum.iife.js"></script>
<script>
  UltrvltRUM.init({ endpoint: 'https://gateway.example.com', app: 'storefront-web' })
</script>

init() is idempotent and safe to call at app bootstrap. It returns { setUser, flush, stopReplay }; setUser and flush are also exported standalone.

What it captures

| Signal | How | Notable attributes | |-------------|---------------------------------------|--------------------| | Page views | Navigation Timing + SPA history hooks | url.full, nav.type | | Web Vitals | web-vitals | web_vital.name, web_vital.value | | JS errors | error + unhandledrejection | exception.type, exception.message | | fetch | monkey-patched window.fetch | http.request.method, http.url, http.response.status_code |

Disable any of them:

init({ endpoint, app, instrument: { vitals: false } })

Session replay

Replay is opt-in (it's heavier and the largest privacy surface). Turn it on with replay: true for defaults, or pass an object to tune it:

init({
  endpoint, app,
  replay: {
    enabled: true,
    sampleRate: 0.2,        // fraction of sampled sessions to record; defaults to sessionSampleRate
    maskPreset: 'strict',   // 'strict' (default) | 'balanced' | 'off'
  },
})

Recordings share the session's session.id, so a replay lines up with the same telemetry spans, and upload to the gateway's dedicated replay lane (<endpoint>/v1/rum/replay). Call rum.stopReplay() to end recording early.

Privacy / masking

Masking is on by default — because you self-host, the recorded DOM never leaves your infrastructure, but the SDK still masks aggressively out of the box:

| maskPreset | Inputs | Visible text | Use for | |--------------|--------|--------------|---------| | strict (default) | masked | masked | anything with sensitive data | | balanced | masked | kept | readable layout for debugging | | off | kept | kept | apps with no sensitive data only |

Fine-grained control: maskAllInputs / maskAllText override the preset, and per-element classes let you exclude regions — ultrvlt-block (fully blocked), ultrvlt-mask (text masked), ultrvlt-ignore (no input events). <canvas> is not recorded unless you set recordCanvas: true.

Backend correlation

The SDK targets the gateway's OTLP/HTTP endpoint (<endpoint>/v1/traces) and injects a W3C traceparent on instrumented fetch calls, so browser spans and the backend spans they trigger share one trace_id and land in the same store — the RUM view and the distributed-trace waterfall are the same data. service.name comes from app; session.id and (optional) user.id ride along on every span.

Sessions & sampling

A session groups telemetry under a stable session.id, persisted to sessionStorage. It rolls over on 30 minutes idle or a 4-hour hard cap. Sampling is decided once per session so a sampled session is captured whole and an unsampled one emits nothing — the injected traceparent always agrees with what's exported.

Ingest key

The browser ingest endpoint is internet-facing, so the gateway can require a per-site ingestKey. When set, the SDK presents it on every telemetry and replay upload. It's a throttling credential to deter public abuse — not a strong secret, and it's safe to ship in your page.

Trace-header scope

propagateTo defaults to same-origin, so traceparent is never leaked to third-party hosts. List additional first-party API origins to extend it.

Development

npm test          # node --test — pure-logic unit tests (ids, session, otlp, replay)
npm run build     # esbuild → dist/ (ESM + IIFE) — requires devDeps installed

The test suite runs with no browser and no bundler. Instrumentation modules (src/instrument/*) require a DOM and are exercised in the browser.