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.

Install

Step 1: Create Application Reference

Navigate to the Installation page in your Middleware Account. In the Real User Monitoring section, select Create New Application and provide the application name, origin(s) and Trace Propogation Target(s) to whitelist. Multiple origins can be listed as a comma-separated list.

Step 2: Import Javascript CDN

Add the following script tag to the head section of your index.html file. The tag can be copied directly from the Installation page upon completing Step 1.

<script
  src="https://cdnjs.middleware.io/browser/libs/0.0.2/middleware-rum.min.js"
  type="text/javascript"
></script>

Step 3: Initialize the SDK

Add the following lines in your index.html file below the script tag entered in Step 2. We recommend copying directly from the Installation page; select the appropriate Application from the list and copy the code snippet. The window.Middleware attribute is set in the script from Step 2.

In the example below, env and recording are optional. recording: "1" is the default value and records the entire user session. To track only browser traces and errors set recording: "0".

<script>
  if (window.Middleware)
  {Middleware.track({
    serviceName: "service_name",
    accountKey: "your-account-token",
    target: "https://<UID>.middleware.io",
    env: "production",
    recording: "1",
  })}
</script>

Step 4: Add Application Version Information [Optional]

Specify your application version, this will help you to identify errors based on application versions.

if(window.Middleware){
    ...
    defaultAttributes: {
        "app.version": "1.0.0"
    }
}

It is recommended to dynamically update the application version based on your release. With dynamic application version you can do root cause analysis of your data.

Step 5: Add User Information [Optional]

To gather user details add key-value pairs, as shown below. Any user metadata can be defined as a key-value pair.

if(window.Middleware){
    ...
    defaultAttributes: {
        name: 'John Doe',
        email: '[email protected]',
        user_type: 'admin', // it can be key value pairs
    }
}

If you need to define attributes post initialization of the SDK, utilize the Middleware.setAttributes method, as exemplified in the following example.

<script>
  if(window.Middleware)
  {Middleware.setAttributes({
    name: "John Doe",
    email: "[email protected]",
    user_type: "admin",
  })}
</script>

Once RUM is configured, metrics should begin appearing on the RUM Dashboard in Middleware within a few minutes. For more information on the RUM Dashboards see here.

Step 6: Add Custom Logs [Optional]

Use these functions to keep track of different types of issues in your system, making it easier to monitor and fix problems.

<script>
if(window.Middleware){
    Middleware.error("Your error message")
    Middleware.error(new Error("Your error message"))
    Middleware.info("info message")
    Middleware.warn("warn message")
    Middleware.debug("debug message")
}
</script>

Connect RUM to Tracing

RUM Tracing allows you to gain insight into the specific actions of your users. You can watch time-stamped videos of user's website interactions, pinpoint performance bottlenecks across your platform, and identify the major causes of customer drop off.

The following installation uses OpenTelemetry B3 Propagator heads. Learn more about B3 Propagation here.

Step 1: Modify Middleware SDK

Add tracePropagationTargets to your SDK from Step 3 of the RUM Installation. The tracePropagationTargets value must be in regex format.

<script>
  if (window.Middleware)
  {Middleware.track({
    serviceName: "service_name",
    accountKey: "<MW_API_KEY>",
    target: "https://<UID>.middleware.io",
    env: "production",
    recording: "1",
    tracePropagationTargets: [/localhost:3000/i, /api.domain.com/i],
    tracePropagationFormat: "w3c",

Step 2: Modify APM SDK

In order to enable Trace Propagation, some languages require the OTEL_PROPAGATORS=b3 environment variable. Those languages are called out in the table below. All other langugages will work with the standard APM install.

Access RUM From Trace List

To access your Session Replay data, navigate to the APM section, select the Trace List tab and choose a trace to view your data.

Supported APMs

API Reference

Configuration Object

Sampling settings

By default, the Middleware RUM agent collects all of the data from all of the users. You can adjust sampling by passing a custom sampler to the tracer property.

The Middleware browser RUM of Opentelemetry JS includes the following samplers:

Session-based sampler

The Middleware browser RUM of Opentelemetry JS includes a custom sampler that supports sessions. Session ratios are preferable to trace ratios, as they keep data from each session intact.

The session-based sampler accepts the following settings:

The following example shows how to collect RUM data from half of the sessions:

<script>
  if(window.Middleware){" "}
  {Middleware.track({
    serviceName: "service_name",
    accountKey: "your-account-token",
    target: "https://<UID>.middleware.io",
    tracer: {
      sampler: new Middleware.SessionBasedSampler({
        ratio: 0.5,
      }),

Troubleshooting

Browser Cookies

The RUM Browser SDK uses cookies to remember a single user session across different pages on your website. These are first-party cookies and stay within your domain; they won't be used to track users across different sites.

Script Integration Issues

If you are experiencing exceptions and errors while integrating the RUM browser SDK, consider moving Middleware packages and scripts earlier in the execution of your application code to avoid collisions with your website's code.

Make sure you have added the following Middleware script with the setTimeout function:

setTimeout(() => {
  if (window.Middleware) {
    Middleware.track({
      serviceName: "sample-service",
      projectName: "sample-project",
      accountKey: "REDACTED",
      target: "<target-url>",
    });
  }
}, 10000);

Unable to See Session Recording

Check if the origin URL (from where the session recording takes place) is correct.

Check your network tab in your developer console if any adblockers or extensions are stopping Middleware requests.

Unhandled Promise Rejection: TypeError: Failed to fetch

This error can be ignored, as it does not impact the Middleware RUM Browser SDK. This issue commonly occurs when an API call is being executed and a user refreshes the page.