@observtech/rum

Browser RUM + Session Replay SDK for Observ — replay-as-context. One call captures a web session (rrweb replay + OpenTelemetry spans + semantic events + JS errors) under a single session.id, so the whole session can be read as context rather than watched as a video.

What it does

A single observ.init() wires all of the following, each stamped with the same session.id so the backend can correlate them:

• Session replay — @rrweb/record DOM capture, sent as gzip chunks.
• Traces — http.client spans for fetch/XHR + page load, over OTLP/HTTP, with W3C traceparent propagation (so front and backend traces stitch).
• Session lifecycle — session.start / session.end events with previous_id chaining, a 30 min inactivity window + 4 h hard cap, and an activity sweep (per-tab sessionStorage by default; opt-in cross-tab).
• End-user identity — enduser.pseudo.id (anonymous, persistent) on every signal, plus enduser.id once you call setUser().
• Semantic events — click, rage_click, navigate as OTel log records.
• Page views — rich app.page_view (referrer, time-on-page, navigation type).
• JS errors — uncaught errors and unhandled promise rejections, observe-only.
• Console forwarding — optionally mirror console.* to the logs pipeline.
• User-interaction spans — optional click/submit/keydown spans with ZoneContextManager (opt-in; pulls in zone.js).
• Consent gate — optionally hold ALL telemetry until GDPR analytics consent.
• PII masking — input values are masked by default (safe-by-default).

observ.init() is idempotent and never throws: any setup failure degrades to "no telemetry" instead of breaking the host page.

Install

yarn add @observtech/rum   # or: npm install / pnpm add

rrweb is pulled in as a transitive dependency and resolved by your bundler. Requires an evergreen browser (uses native CompressionStream, fetch, sessionStorage, history).

Configure

Call it as early as possible, before the first fetch/XHR you want traced:

import { observ } from '@observtech/rum'

observ.init({
  endpoint: 'https://observ.example.com', // Observ backend base URL
  key: '<api-key>', // sent as the x-observ-key header
})

Main options:

| Option | Type | Default | Role | | ------------------------------------------------ | --------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- | | endpoint | string | — | Base URL of the Observ backend (/v1/... paths are appended). | | key | string | — | API key sent as x-observ-key (empty ⇒ header omitted). | | propagateTraceHeaderCorsUrls | (string \| RegExp)[] | [] | Cross-origin backends allowed to receive the W3C traceparent header. | | disableReplay | boolean | false | Keep tracing/events but turn off the heavy rrweb replay. | | privacy | PrivacyOptions | masked | PII masking of the replay stream (see below). | | serviceName / serviceVersion / environment | string | — | Resource attributes (service.name, …) stamped on every signal. | | sampleRate | number | 1 | Head-based trace sampling ratio in [0,1) (ParentBased). | | propagateBaggage | boolean | false | Send session.id to allowed backends via the W3C baggage header. | | disableMetrics | boolean | false | Turn off Core Web Vitals + OTLP metrics. | | sessionInactivityMs | number | 30 min | Inactivity window before the session.id rotates. | | sessionMaxDurationMs | number | 4 h | Hard cap on a single session's duration (rotates even while active). | | crossTabSessions | boolean | false | Share one session across tabs (localStorage) instead of per-tab. | | disablePseudoUser | boolean | false | Disable the persistent pseudonymous enduser.pseudo.id. | | forwardConsole | boolean \| ConsoleLevel[] | false | Mirror console.* to the logs pipeline (all levels, or a subset). | | disablePageViews | boolean | false | Turn off rich app.page_view events. | | userInteraction | boolean | false | Interaction spans + ZoneContextManager (opt-in; pulls in zone.js). | | requireConsent | boolean | false | Hold ALL telemetry until analytics consent is present (see below). | | consentKey / consentGrantedValues | string / string[] | observ.consent / ['granted','true','1','yes','all'] | Where/what consent is read from. |

Privacy / PII masking

The replay records the live DOM, so input values are PII. Masking is on by default: omit privacy entirely and every <input>/<textarea>/<select> value is masked. Three CSS classes mark sensitive nodes declaratively:

• observ-mask — mask the element's text
• observ-block — drop the element from the replay
• observ-ignore — record the element but ignore its input value

observ.init({
  endpoint: 'https://observ.example.com',
  key: '<api-key>',
  privacy: {
    maskAllInputs: true, // default; set false only on a surface free of PII
    maskAllText: false, // true masks ALL visible text (degrades the replay)
  },
})

End-user identity

Every signal carries a pseudonymous enduser.pseudo.id (persisted in localStorage, anonymous). After sign-in, attach the authenticated identity; clear it on sign-out:

observ.setUser({ id: user.id, role: user.role, name: user.name }) // → enduser.id/role/name
observ.clearUser() // on logout (the pseudo id persists)

Sessions

A session.id is shared by every signal. It rotates after 30 min of inactivity or a 4 h hard cap, emitting session.start (with session.previous_id on a continuation) and a best-effort session.end (with session.duration_ms). Sessions are per-tab (sessionStorage) by default — two tabs are two visits, by design. Set crossTabSessions: true to share one session across a visitor's tabs.

Console forwarding (optional)

observ.init({ endpoint, key, forwardConsole: ['warn', 'error'] }) // or `true` for all levels

Off by default — console output can be noisy and may contain PII. The original console.* is always still called.

User-interaction spans (optional)

observ.init({ endpoint, key, userInteraction: true })

Turns clicks/submits/keydowns into spans with a ZoneContextManager so trace context survives the async work they trigger. Opt-in: it pulls in zone.js, which monkey-patches the host's global timers/Promise on import — so it is dynamically loaded only when enabled (the default bundle and host globals stay untouched).

Consent (GDPR)

Hold ALL telemetry until analytics consent is present (no session, no persistent id, no network):

observ.init({ endpoint, key, requireConsent: true }) // reads cookie/localStorage `observ.consent`
// …later, from your consent banner:
observ.grantConsent() // persists consent + starts the waiting SDK
observ.revokeConsent() // clears consent + shuts the SDK down

The SDK also auto-starts if another tab grants consent (via the storage event) or the banner writes the key in this tab (a light poll picks it up).

Stop (optional)

await observ.shutdown() // stops replay (flushing the residual) + tears down OTel

The SDK already flushes on visibilitychange/pagehide, so shutdown() is mainly for SPA teardown or tests.

Documentation

• Full usage & backend (observ-server) setup — endpoints, CORS, API keys, session storage, troubleshooting: see the Observ docs (docs/session-replay-rum-sdk.md).
• Building, releasing & maintaining this package: docs/observ-rum-sdk-maintainers.md.

MIT licensed.