Browser RUM - Getting Started

This guide walks you through setting up Real User Monitoring (RUM) with JavaScript in the browser. These instructions can also be found on the Installation page in your Middleware account.

Overview#

The Middleware Browser RUM SDK collects real user activity and frontend performance data from your web application. It helps you investigate slow pages, JavaScript errors, and failed requests in the context of an affected user session.

Collected data includes page loads, Core Web Vitals, JavaScript errors, network requests, and sessions. Session Replay adds visual context, while distributed tracing connects frontend activity with instrumented backend services when trace correlation is configured.

How it works#

The Middleware RUM SDK runs in the user's browser and automatically collects frontend telemetry.

Once initialized, the SDK captures:

• Page views: Initial page loads and route changes in single-page applications.
• Performance: Core Web Vitals, resource timings, and long tasks.
• Errors: JavaScript runtime errors and browser errors.
• Network requests: Fetch and XHR requests, including timing information.
• User interactions: Click actions and session activity.
• Session Replay: Browser session recordings for investigating user issues.

The SDK sends collected data to your Middleware account, where you can analyze application performance, investigate errors, and review user sessions.

You can also connect frontend requests with backend APM traces using distributed tracing.

Prerequisites#

Before installing the SDK, make sure you have:

• A Middleware account.
• Access to your application's HTML or frontend source code.
• Your Middleware RUM application credentials.
• Permission to update and deploy your web application.

Installation#

1<script
2  src="https://cdnjs.middleware.io/browser/libs/0.0.2/middleware-rum.min.js"
3  type="text/javascript"
4  crossorigin="anonymous">
5</script>

1<script>
2  if (window.Middleware) {
3    Middleware.track({
4      projectName: "my-application",
5      serviceName: "mw-application",
6      accountKey: "<MW_ACCOUNT_KEY>",
7      target: "https://<MW_UID>.middleware.io",
8      env: "production"
9    });
10  }
11</script>

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8" />
5
6  <script
7    src="https://cdnjs.middleware.io/browser/libs/0.0.2/middleware-rum.min.js"
8    type="text/javascript"
9    crossorigin="anonymous">
10  </script>
11
12  <script>
13    if (window.Middleware) {
14      Middleware.track({
15        projectName: "my-application",
16        serviceName: "mw-application",
17        accountKey: "<MW_ACCOUNT_KEY>",
18        target: "https://<MW_UID>.middleware.io",
19        env: "production"
20      });
21    }
22  </script>
23</head>
24
25<body>
26  <div id="app"></div>
27</body>
28</html>

Optional configuration#

After verifying that RUM data is being collected, you can configure session recording, privacy controls, user attributes, distributed tracing, and sampling.

Configure session recording#

Session recording is enabled by default.

Use the recording parameter to control session capture:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6  recording: "1"
7});

Use recording: "0" if you want to monitor frontend performance and errors without recording user sessions.

Mask sensitive information#

Use recordingOptions to control what is captured in Session Replay.

For example:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6  recording: "1",
7
8  recordingOptions: {
9    maskAllInputs: true,
10    maskTextSelector: ".pii, [data-pii]",
11    blockSelector: ".auth-widget, .payment-form"
12  }
13});

These options apply to Session Replay.

Initialize RUM after user consent#

If your application requires user consent before collecting analytics or session recordings, initialize the SDK only after the appropriate consent is granted.

For example:

1function hasAnalyticsConsent() {
2  return document.cookie.includes("consent_analytics=true");
3}
4
5if (hasAnalyticsConsent() && window.Middleware) {
6  Middleware.track({
7    projectName: "my-application",
8    serviceName: "mw-application",
9    accountKey: "<MW_ACCOUNT_KEY>",
10    target: "https://<MW_UID>.middleware.io",
11    recording: "1"
12  });
13}

Adapt the consent check to your application's consent management system.

Add application and user attributes#

Use custom attributes to filter sessions and investigate issues affecting specific application versions or user groups.

Add application version#

Add the application version during SDK initialization:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6
7  defaultAttributes: {
8    "app.version": "1.0.0"
9  }
10});

This helps identify errors and performance changes associated with a particular release.

Add user attributes#

You can also add user metadata:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6
7  defaultAttributes: {
8    user_type: "admin",
9    subscription_plan: "enterprise"
10  }
11});
12To update attributes after initialization:
13Middleware.setAttributes({
14  user_type: "admin",
15  subscription_plan: "enterprise"
16});

Call Middleware.setAttributes() only after Middleware.track() has initialized the SDK.

Privacy recommendation: Prefer non-sensitive attributes such as application version, environment, and user type. Avoid sending personal information unless it is necessary and permitted by your privacy requirements.

Add custom browser logs#

Use the Middleware SDK to capture custom frontend logs and errors.

Middleware.info("User opened checkout page");

Middleware.warn("API response is slower than expected");

Middleware.debug("Loading user preferences");

Middleware.error("Failed to load payment details");

You can also record JavaScript errors:

1try {
2  throw new Error("Payment request failed");
3} catch (error) {
4  Middleware.error(error);
5}

These logs provide additional context when investigating frontend issues.

Configure distributed tracing#

Distributed tracing connects frontend user activity with backend application traces.

This lets you follow a request from the browser to the backend service and investigate slow or failed requests in the same context.

Prerequisites#

Before enabling distributed tracing:

• Install Middleware APM instrumentation on your backend application.
• Ensure the backend accepts the configured trace propagation headers.
• Configure your backend's CORS policy to allow the required tracing headers for cross-origin requests.

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "frontend-service",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6
7  tracePropagationTargets: [
8    /localhost:3000/i,
9    /api.example.com/i
10  ],
11
12  tracePropagationFormat: "b3"
13});

Configure sampling#

By default, the Browser RUM SDK collects all eligible data.

You can configure sampling to reduce the amount of telemetry collected.

For example, to sample 50% of sessions:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6
7  tracer: {
8    sampler: new Middleware.SessionBasedSampler({
9      ratio: 0.5
10    })
11  }
12});

The ratio value ranges from 0.0 to 1.0.

Session-based sampling is useful when you want to keep telemetry from an individual user journey together.

Configuration reference#

Exclude bot traffic#

By default, the SDK excludes known crawlers and automated browser traffic.

To include traffic from automated browsers such as Playwright or Puppeteer:

1Middleware.track({
2  projectName: "my-application",
3  serviceName: "mw-application",
4  accountKey: "<MW_ACCOUNT_KEY>",
5  target: "https://<MW_UID>.middleware.io",
6  blockBotTraffic: false
7});

This can be useful when validating RUM instrumentation using automated tests.

Troubleshooting#

No RUM data in Middleware#

If the application is running but RUM data does not appear:

• Verify that the Middleware JavaScript SDK loads successfully.
• Confirm that accountKey and target are correct.
• Check that Middleware.track() is called after the SDK script loads.
• Verify that the application origin is configured correctly.
• Check the browser's Network tab for blocked or failed requests.
• Confirm that browser extensions or ad blockers are not blocking the SDK.

Middleware SDK is not initialized#

If window.Middleware is undefined:

• Verify that the SDK CDN URL is correct.
• Place the SDK script before the initialization code.
• Check for Content Security Policy restrictions.
• Review the browser console for script-loading errors.

Session Replay is not available#

If RUM data appears but recordings are missing:

• Confirm that recording is set to "1".
• Verify that the application origin matches the configured origin.
• Check that recording is allowed by your consent configuration.
• Verify that session recording requests are not blocked by browser extensions.

SPA route changes are not captured#

If your application uses client-side routing:

• Confirm that the router updates the browser URL.
• Verify that route changes use the History API or URL hash changes.
• Check whether new views appear in Middleware after navigation.

Frontend and backend traces are not connected#

If frontend requests and backend traces appear separately:

• Verify that the backend has Middleware APM instrumentation installed.
• Confirm that tracePropagationTargets matches the backend host.
• Make sure the frontend and backend use compatible propagation formats.
• Check CORS settings to ensure tracing headers are allowed.
• Verify that tracing headers reach the backend without being removed by proxies.

RUM data is missing from automated browser tests#

The SDK excludes known bot and automated browser traffic by default.

If you're testing with Playwright, Puppeteer, or another headless browser, set:

blockBotTraffic: false

Content Security Policy blocks the SDK#

If your application uses a Content Security Policy, allow the Middleware CDN and ingestion endpoint.

For example:

1Content-Security-Policy:
2  default-src 'self';
3  script-src 'self' https://cdnjs.middleware.io;
4  connect-src 'self' https://<MW_UID>.middleware.io;
5  img-src 'self' data:;

If you use inline initialization scripts, allow them using a CSP nonce or hash rather than broadly enabling unsafe inline scripts.

Adjust the policy to match your application's existing security requirements.

Session IDs change unexpectedly#

The Browser RUM SDK uses first-party cookies to maintain user sessions.

The _mwRumSessionId_x cookie stores session information. Its expiration is extended with user activity, subject to the SDK's maximum session duration.

If sessions are split unexpectedly, check whether browser privacy settings or application cookie policies are clearing the cookie.

If the issue persists, contact Middleware Support at [email protected].