Collecting RUM Data Through A Proxy

Instead of loading the DebugBear snippet from our CDN and sending real user monitoring data directly to DebugBear, you can route both through your own infrastructure.

Why use a proxy for RUM data?

Routing requests through your own servers has the following advantages:

• Higher tracking rate: the snippet and its data look like first-party requests, so ad blockers don't block them
• Better privacy: visitor IP addresses are never shared directly with DebugBear

tip

Do you need visitors to connect to an EU server? DebugBear offers prebuilt proxy infrastructure in the EU. Contact support to set this up.

What requests you need to proxy

DebugBear RUM data involves three requests made on your website:

• rum-<version>.js: the script for data collection
• <snippetKey>.config.json: your configuration options like page groups or sampling rate
• Data endpoint: where incoming RUM data is sent to

With the proxy setup, your server needs to handle each of these requests.

info

Older versions of the embed code may use an unversioned script that combines the data collection logic and settings.

How to set up a RUM proxy

1. Serve the DebugBear snippet and its config from your own website
2. Create an endpoint on your website that forwards the monitoring data as it's collected
3. Update the proxy settings in DebugBear
4. Update the script tag on your website

We'll explain each step in more detail below.

tip

Entering the Proxy Base Path in the Proxy Setup section fills in the data endpoint, snippet URL and config URL for you, and you can edit any of them afterwards.

Reset Proxy Settings puts all of them back to loading from and sending to DebugBear directly, once you save.

1. Serve the DebugBear snippet and its config from your own website

Pick a path on your website, for example /dbb/, and serve the two files under it by fetching them from DebugBear. With the files under /dbb/, your visitors will request:

• https://example.com/dbb/rum-1.2.0.js
• https://example.com/dbb/abcd0123.config.json

DebugBear serves the originals under the same file names at https://cdn.debugbear.com/. To see the two file names for your snippet, go to your RUM Settings tab and expand the Proxy Setup section: they are shown at the end of the Snippet Proxy URL and Config Proxy URL fields.

info

Forward the request for whatever file name was asked for, rather than hardcoding the current version. When DebugBear releases a new snippet version, you can then update the script tag on your website and your proxy keeps working without a code change.

Here's an example using Node.js with Express that streams the response straight through:

import { Readable } from "node:stream";

const DEBUGBEAR_CDN = "https://cdn.debugbear.com";
// Only the two files the snippet requests
const RUM_FILE = /^(rum-\d+\.\d+\.\d+\.js|[A-Za-z0-9]+\.config\.json)$/;

app.get("/dbb/:file", async (req, res) => {
  if (!RUM_FILE.test(req.params.file)) {
    return res.sendStatus(404);
  }
  const upstream = await fetch(`${DEBUGBEAR_CDN}/${req.params.file}`);
  if (!upstream.ok) {
    return res.sendStatus(upstream.status);
  }
  res.status(200);
  for (const header of ["content-type", "cache-control", "etag"]) {
    const value = upstream.headers.get(header);
    if (value) {
      res.set(header, value);
    }
  }
  // Required: the script tag carries an integrity hash and the config is
  // fetched with CORS, so both files need to be readable cross-origin
  res.set("Access-Control-Allow-Origin", "*");
  Readable.fromWeb(upstream.body).pipe(res);
});

Add caching in front of this route, for example in your CDN or with an in-memory cache, so that the files aren't fetched from DebugBear on every visit. The config file changes whenever you save your RUM settings, so don't cache it for longer than an hour.

info

Avoid downloading the files and hosting static copies on your server. If you do, configuration changes you make on the DebugBear website won't be applied until you copy the files again.

2. Forward RUM data as it's collected

Next, you need to create a POST endpoint on your website that the RUM data can be sent to. We'll use /dbb/saverumdata as an example, which is the path the Proxy Base Path setting assumes.

This endpoint then needs to forward the data to https://data.debugbear.com.

You can use the following headers with the request:

• x-rum-token: providing this token bypasses IP-based rate limiting and referrer-based domain matching
• x-rum-country: normally DebugBear infers the country based on the IP address, but when proxying data, you can set it directly

You can find the x-rum-token value in your RUM Settings tab: expand the Proxy Setup section and copy the RUM Token shown under the Data Endpoint field.

Here's an example using Node.js and Express:

// Support JSON and text bodies to support both
// navigator.sendBeacon and fetch data reports
const bodyParser = require("body-parser");
app.use(bodyParser.json());
app.use(express.text());

app.post("/dbb/saverumdata", async (req, res) => {
  // CORS header needed if the domain where you host the proxy
  // code does not match your website domain
  res.set("Access-Control-Allow-Origin", "*");
  await axios.post(
    "https://data.debugbear.com",
    // The body may be either text or JSON, parse text if necessary
    typeof req.body === "string" ? JSON.parse(req.body) : req.body,
    {
      headers: {
        "x-rum-token": "ABCDSTU124",
        // Pass a two-letter country code in here
        // Many cloud environments provide options to obtain
        // the country code through a header in req.headers
        "x-rum-country": "FR",
      },
    },
  );
  res.json({});
});

3. Update the proxy settings in DebugBear

1. Go to the DebugBear RUM Settings tab
2. Expand the Proxy Setup section
3. Enter the path your proxy lives under as the Proxy Base Path, for example https://example.com/dbb. A path on the same site (/dbb) or a protocol-relative URL (//example.com/dbb) works too. This fills in the three fields below it:
   • Data Endpoint: https://example.com/dbb/saverumdata
   • Snippet Proxy URL: https://example.com/dbb/rum-1.2.0.js. The file name at the end of this field can't be edited: it always follows the current snippet version, so it stays in step with the integrity hash in the script tag.
   • Config Proxy URL: https://example.com/dbb/abcd0123.config.json. The file name can't be edited here either: it is your snippet key followed by .config.json.
4. If your setup differs, edit any of those three fields directly. Change the Data Endpoint if your data route isn't called /saverumdata, or point the Config Proxy URL at a different path if you serve the config file from a different place. To proxy only part of the setup, clear the fields you don't need: an empty Snippet Proxy URL or Config Proxy URL loads that file from the DebugBear CDN.
5. Click Save Settings

tip

Changing the proxy settings changes the generated embed code. Copy the updated tag after saving. When a new snippet version is released, the Snippet Proxy URL follows it automatically; you only need to copy the new tag.

4. Update the script tag on your website

Copy the script tag from the Install RUM Analytics Snippet box on the RUM Settings tab and replace the one on your website. It now loads the script from your snippet proxy URL, tells the snippet where to find its config, and sends data to your data endpoint.

Use the generated tag rather than writing your own. It pins the snippet version and its integrity hash, and preloads the config file, so the snippet starts collecting data as early as possible.

Check that data is recorded correctly

After the proxy is set up, you can check if it's working correctly. For example, if your website is example.com:

1. You should see a JavaScript request to example.com/dbb/rum-1.2.0.js and a request to example.com/dbb/abcd0123.config.json
2. After several seconds (or if you switch to another tab and back) you should see data being posted to example.com/dbb/saverumdata
3. The RUM page view should then show up in your DebugBear dashboard

(Remember to switch to viewing page views from "All" devices if testing on desktop.)

Using a Google Cloud Function to proxy DebugBear RUM data

This GitHub repository provides a RUM proxy implementation that's easy to deploy as a Google Cloud Function.

You may also find it useful as a starting point for an AWS Lambda function or a custom deployment setup.

Need help?

If you need help with your custom proxy setup for DebugBear RUM data, please contact support.