Browser RUM SDK

The MoleSignal Browser RUM SDK collects browser sessions, page views, user interactions, frontend errors, Web Vitals, network resources, and trace correlation context.

Prerequisites

the MoleSignal deployment URL;
a stable application identifier, such as checkout-web;
a dedicated token authorized to send RUM data into the target workspace.

clientToken is included in browser code and is visible to users. Never use an owner, administrator, or personal token. Use the application-bound msrum_ client token created by the data-source guide.

Install and initialize

Install the package

npm install @molesignal/browser-rum

Initialize the SDK once

import { initRum } from '@molesignal/browser-rum';

const rum = initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  service: 'web-frontend',
  env: 'production',
  version: 'v1.4.0',
  sessionSampleRate: 100,
  trackUserInteractions: true,
});

Initialize the SDK before the application router mounts to capture the first page view. Importing and initializing the package during server-side rendering is safe; browser instrumentation starts only when browser APIs exist.

Verify the first session

Open RUM → Overview and select a time range that includes the current time. Confirm that the application appears, then open Sessions to inspect the first session.

The site value can be a MoleSignal origin, /api base, or /api/v1 base. The SDK normalizes the value and sends data to the RUM endpoints beneath /api/v1/rum.

Identify users and add context

Provide the user during initialization when possible so the first session carries the correct identity.

const rum = initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  user: { id: currentUser.id, plan: currentUser.plan },
  globalContext: { region: 'eu-west-1' },
});

rum.setUser({ id: 'user-42', plan: 'enterprise' });
rum.setGlobalContextProperty('feature_flags', ['new-checkout']);

When no user is provided, the SDK creates a stable anonymous identifier in localStorage. Set trackAnonymousUser: false when privacy policy does not allow persistent anonymous identity.

Add custom actions, errors, and views

rum.addAction('Checkout submitted', {
  cart_size: 3,
  payment_method: 'card',
});

try {
  await submitOrder();
} catch (error) {
  rum.addError(error, { component: 'CheckoutForm' });
}

// Use this when trackViewsManually is true.
rum.startView('Order confirmation');

Call rum.flush() before a controlled navigation or shutdown to wait for queued events. Call rum.stop() to remove instrumentation and flush the client.

Automatic collection defaults

Data	Option	Default
Page views	`trackViewsManually`	Automatic History API tracking (`false`)
Fetch, XHR, and resource timing	`trackResources`	`true`
Long tasks	`trackLongTasks`	`true`
Web Vitals	`trackWebVitals`	`true`
Clicks and form submissions	`trackUserInteractions`	`false`
Rage and dead clicks	`trackFrustrations`	Same as interaction tracking
Runtime errors	built in	Enabled
`console.error`	`trackConsoleErrors`	`false`
DOM session replay	`sessionReplaySampleRate`	`0`

Connect browser requests to traces

The fetch and XMLHttpRequest integrations read W3C traceparent from the outgoing request, response, or a Server-Timing entry named traceparent. For cross-origin APIs, expose the response headers and allow the origin explicitly:

Access-Control-Expose-Headers: traceparent, server-timing

allowedTracingUrls: [
  'https://api.example.com',
  /^https:\/\/edge-\w+\.example\.com\//,
]

Next steps

Data sampling

Control session and replay volume independently.

Privacy

Keep sensitive values on the user’s device.

Session replay

Record and replay DOM changes safely.

Source maps & symbols

Restore minified browser stacks and review the unified artifact workflow.

Getting Started

Observe

Reliability

AI Ops

Data

Collaboration

Admin

Deploy & Operate

Prerequisites

Install and initialize

Identify users and add context

Add custom actions, errors, and views

Automatic collection defaults

Connect browser requests to traces

Next steps

Data sampling

Privacy

Session replay

Source maps & symbols

​Prerequisites

​Install and initialize

​Identify users and add context

​Add custom actions, errors, and views

​Automatic collection defaults

​Connect browser requests to traces

​Next steps

Data sampling

Privacy

Session replay

Source maps & symbols

Prerequisites

Install and initialize

Identify users and add context

Add custom actions, errors, and views

Automatic collection defaults

Connect browser requests to traces

Next steps