@rushobservability/rum-sdk

Real User Monitoring (RUM) browser SDK for Rush Observability. Lightweight, dependency-light, and framework-agnostic — it captures Web Vitals, JS errors, page views, interactions, resource timing, and optional session replay, then ships them to your Rush ingest endpoint.

Install

npm install @rushobservability/rum-sdk

Usage

import RushRUM from '@rushobservability/rum-sdk'

RushRUM.init({
  endpoint: 'https://your-rush-host/rum/ingest',
  app: { name: 'my-web-app', version: '1.4.2' },
  environment: 'production',

  // What to collect (defaults shown)
  trackWebVitals: true,     // LCP, INP, CLS, FCP, TTFB (via web-vitals)
  trackErrors: true,        // uncaught errors + unhandled rejections
  trackPageViews: true,     // SPA-aware page views
  trackLongTasks: true,     // long tasks + Long Animation Frames (LoAF)
  trackInteractions: false, // click/input + frustration signals
  trackResources: false,    // resource timing entries
  trackSessionReplay: false,// DOM session replay (via rrweb)

  // Optional
  sampleRate: 1.0,                       // 0..1
  user: () => ({ id: currentUserId }),   // attach a user id
  propagateTraces: { origins: [/^https:\/\/api\.example\.com/] },

  // Replay privacy (default 'mask' — masks ALL text + inputs, blocks media)
  replayPrivacy: 'mask',

  // Mutate/drop events before they're queued (return null to drop)
  beforeSend: (event) => event,
})

// Custom events
RushRUM.trackEvent('checkout_completed', { plan: 'pro', amount: 49 })

// Dynamically set/override the current user (overrides config.user)
RushRUM.setUser({ id: 'user-123' })
RushRUM.setUser(null) // clear

// Attributes merged into every event's `attributes` (event keys win)
RushRUM.setGlobalAttributes({ tenant: 'acme', release: 'canary' })
RushRUM.clearGlobalAttributes()

// Flush the queue manually (e.g. before a hard navigation)
RushRUM.flush()

// Stop collecting + detach handlers/timers (tests, SPA hot-reload)
RushRUM.destroy()

Configuration

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | — (required) | Rush RUM ingest URL | | app | { name, version? } | — (required) | Application identity | | environment | string | — | e.g. production, staging | | sampleRate | number | 1.0 | Fraction of sessions to record (0–1) | | user | () => { id? } \| null | — | Resolver for the current user id | | trackWebVitals | boolean | true | Core Web Vitals | | trackErrors | boolean | true | Uncaught errors + promise rejections | | trackPageViews | boolean | true | SPA-aware page views | | trackLongTasks | boolean | true | Long tasks (>50ms) + Long Animation Frames (LoAF), via PerformanceObserver | | trackInteractions | boolean | false | Click/input events + frustration signals (rage/dead/error clicks) | | trackResources | boolean | false | Resource timing | | trackSessionReplay | boolean | false | DOM session replay (rrweb) | | propagateTraces | { origins: RegExp[] } | — | Inject trace headers on matching XHR/fetch origins | | replayEndpoint | string | <endpoint>/rum/replay/ingest | Override the replay ingest URL | | captureQueryParams | boolean | false | Keep query strings + hash on captured URLs. Off by default — query params often carry tokens/PII | | maskInteractionText | boolean | false | Drop clicked-element text from interaction events (keep only tag/id/classes) | | compress | boolean | false | gzip the request body (Content-Encoding: gzip) via CompressionStream. Only enable if your ingest endpoint decodes gzip — the current Rush backend does not. The unload/beacon path is always uncompressed | | beforeSend | (event) => RumEvent \| null | — | Mutate or drop each event before it's queued (return null to drop). A throwing hook never breaks collection | | replayPrivacy | 'mask' \| 'mask-user-input' \| 'allow' | 'mask' | Replay masking level (see below) | | replayMaskSelector | string | — | Extra CSS selector for text/elements to mask in replay (merged with [data-pii]) | | replayBlockSelector | string | — | Extra CSS selector for elements to block (not record) in replay | | replayUnmaskSelector | string | — | Extra CSS selector for text to leave un-masked in replay (only applies when text masking is on) | | replayBeforeAddEvent | (event) => unknown \| null | — | Scrub or drop replay events before buffering (return null to drop) |

Methods

| Method | Description | |---|---| | RushRUM.init(config) | Initialize and start collection (SSR-safe no-op; ignores duplicate calls) | | RushRUM.trackEvent(name, attributes?) | Send a custom event | | RushRUM.setUser(user \| null) | Dynamically set/override the user id (overrides config.user); null clears | | RushRUM.setGlobalAttributes(attrs) | Merge attributes into every subsequent event's attributes (event-specific keys win) | | RushRUM.clearGlobalAttributes() | Clear all global attributes | | RushRUM.flush() | Force-flush the queue | | RushRUM.destroy() | Stop collection; detach all observers/timers/listeners |

Replay privacy

As of 0.2.0, session replay is private by default — a behavior change from 0.1.x, which masked inputs but recorded all visible text. The replayPrivacy level maps to rrweb options:

| Level | Inputs | Text | Media | |---|---|---|---| | 'mask' (default) | masked | all text masked | img,video,audio,picture,source,canvas blocked | | 'mask-user-input' | masked | visible | recorded | | 'allow' | recorded | visible | recorded |

[data-pii] is always masked regardless of level. replayMaskSelector / replayBlockSelector add more, and replayUnmaskSelector carves out exceptions when text masking is on.

Reliability

Event batches are sent through a hardened transport: failed sends (network error, HTTP 429/5xx) are retried up to 3× with exponential backoff + jitter. Batches that still fail — or any sent while navigator.onLine === false — are persisted to localStorage (versioned key, ~1 MB / 50-batch cap, oldest dropped on overflow) and drained oldest-first on the next init() and whenever the online event fires. The in-memory queue is capped at 1000 events (oldest dropped). The unload/beacon path uses sendBeacon (uncompressed, no retry). All of this is best-effort and never throws into your app.

Frustration signals

When trackInteractions is enabled, the SDK emits frustration events:

• rage_click — more than 3 clicks on the same element within 1s.
• dead_click — a click on an interactive element that produces no DOM mutation, URL change, or scroll within 3s (conservative, to avoid false positives).
• error_click — a JS error fires within 1s of a click.

sampleRate is decided once per session and applied to every event, so sampled sessions are complete (no half-captured sessions).

init() is a no-op outside the browser (SSR-safe) and ignores duplicate calls. RushRUM.destroy() stops collection and detaches handlers/timers (useful for tests / SPA hot-reload).

Build

npm install
npm run build      # tsc → dist/
npm run typecheck  # type-check only

License

MIT