Proxy Your Browser RUM Data

Upgrade to Browser SDK 4.34.0 or later to avoid security vulnerabilities in your proxy configuration.

Overview

The RUM Browser SDK can be configured to send requests through a proxy. When you set the SDK's proxy initialization parameter to a URL such as https://www.example-proxy.com/any-endpoint, all RUM data is sent to that URL using the POST method. The RUM data still needs to be forwarded to Datadog from the proxy.

Prerequisite proxy setup

To successfully forward a request to Datadog, your proxy must

Build the Datadog intake URL.
Add an X-Forwarded-For header containing the request client IP address for accurate geoIP.
Forward the request to the Datadog intake URL using the POST method.
Leave the request body unchanged.

For security reasons, remove any HTTP headers that potentially contain sensitive information, such as the cookie header.
The request body can contain binary data and should not be converted to a string. Make sure your proxy implementation forwards the raw body without conversion.
Make sure your proxy implementation does not allow a malicious actor to send requests to a different server. For example: https://browser-intake-datadoghq.com.malicious.com.

Build the Datadog intake URL

Your Datadog intake URL should have the format <INTAKE_ORIGIN>/<PATH><PARAMETERS> (for example, https://browser-intake-datadoghq.eu/api/v2/rum?ddsource=browser&...).

intake origin	The Datadog intake origin corresponds to your `site` initialization parameter. The Datadog intake origin corresponding to your site parameter should be defined in your proxy implementation. The intake origin for your Datadog site is `https://browser-intake-datadoghq.com`. The intake origin for your Datadog site is `https://browser-intake-us3-datadoghq.com`. The intake origin for your Datadog site is `https://browser-intake-us5-datadoghq.com`. The intake origin for your Datadog site is `https://browser-intake-datadoghq.eu`. The intake origin for your Datadog site is `https://browser-intake-ap1-datadoghq.com`. The intake origin for your Datadog site is `https://browser-intake-ap2-datadoghq.com`. The intake origin for your Datadog site is `https://browser-intake-ddog-gov.com`.
path	The path contains the API version and the product (for example, `/api/v2/rum` for RUM data or `/api/v2/replay` for Session Replay data). The path for each request can be accessed in the request's `ddforward` parameter (for example, `https://www.example-proxy.com/any-endpoint?ddforward=%2Fapi%2Fv2%2Frum%3Fddsource%3Dbrowser`).
parameters	The request parameters (for example, `ddsource=browser&...`) can be accessed in the request's `ddforward` parameter (for example, `https://www.example-proxy.com/any-endpoint?ddforward=%2Fapi%2Fv2%2Frum%3Fddsource%3Dbrowser`).

intake origin

The Datadog intake origin corresponds to your site initialization parameter. The Datadog intake origin corresponding to your site parameter should be defined in your proxy implementation.

path

The path contains the API version and the product (for example, /api/v2/rum for RUM data or /api/v2/replay for Session Replay data).

The path for each request can be accessed in the request's ddforward parameter (for example, https://www.example-proxy.com/any-endpoint?ddforward=%2Fapi%2Fv2%2Frum%3Fddsource%3Dbrowser).

parameters The request parameters (for example, ddsource=browser&...) can be accessed in the request's ddforward parameter (for example, https://www.example-proxy.com/any-endpoint?ddforward=%2Fapi%2Fv2%2Frum%3Fddsource%3Dbrowser).

SDK setup

Configure the URL of the proxy in the proxy initialization parameter:

import { Datacenter, datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    applicationId: '<DATADOG_APPLICATION_ID>',
    clientToken: '<DATADOG_CLIENT_TOKEN>',
    site: '',
    proxy: '<YOUR_PROXY_URL>',
});

window.DD_RUM.onReady(function() {
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        proxy: '<YOUR_PROXY_URL>',
    });
});

window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        proxy: '<YOUR_PROXY_URL>'
    });

The RUM Browser SDK adds a ddforward query parameter to all requests to your proxy. This query parameter contains the URL path and parameters that all data must be forwarded to.

For example, with a site set to datadoghq.eu and a proxy set to https://example.org/datadog-intake-proxy, the RUM Browser SDK sends requests to a URL like this: https://example.org/datadog-intake-proxy?ddforward=%2Fapi%2Fv2%2Frum%3Fddsource%3Dbrowser. The proxy forwards the request to https://browser-intake-datadoghq.eu/api/v2/rum?ddsource=browser.

Passing a function to the `proxy` initialization parameter

The proxy initialization parameter also supports a function input. This function allows you to have more control on how the path and parameters are added to the proxy URL.

This function receives an object with the following properties:

path: the path for the Datadog requests (example: /api/v2/rum)
parameters: the parameters of the Datadog requests (example: ddsource=browser&...)

import { Datacenter, datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    applicationId: '<DATADOG_APPLICATION_ID>',
    clientToken: '<DATADOG_CLIENT_TOKEN>',
    site: '',
    proxy: (options) => `https://www.proxy.com/foo${options.path}/bar?${options.parameters}`,
});

window.DD_RUM.onReady(function() {
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        proxy: (options) => `https://www.proxy.com/foo${options.path}/bar?${options.parameters}`,
    })
})

window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        proxy: (options) => `https://www.proxy.com/foo${options.path}/bar?${options.parameters}`
    });

Note:

Some privacy blockers already target the intake URL patterns, so you may want to take that into account when building your proxy URL.
The proxy function is called for each request, so it should avoid any heavy computation.
JSP web applications need to use the \ escape character to properly propagate these parameters to the browser. For example:
```
proxy: (options) => 'http://proxyURL:proxyPort\${options.path}?\${options.parameters}',
```

Before Browser SDK v4.34.0, the proxyUrl initialization parameter was used, and the Datadog intake origin was included in the ddforward attribute. The proxy implementation was in charge of validating this host, and failure to do so resulted in various vulnerabilities.

The Datadog intake origin needs to be defined in your proxy implementation to ensure security.

To avoid security vulnerabilities, you must upgrade to Browser SDK 4.34.0 or later.