• /
  • Log in
  • Free account

Browser data in distributed tracing

If you use browser to monitor end-user browser activity, you can now see end-user-originating browser-side traces in distributed tracing. This document contains:

Benefits of browser data in distributed tracing

By enabling New Relic to report browser data to distributed tracing, you can see the connection between front-end activity and back-end activity. You can see across a full transaction, from time spent by an end user in the web browser, to network activity, to associated back-end services.

Benefits of this feature:

  • Quickly spot latencies, errors, and anomalies in the browser or network
  • Resolve customer-facing problems more quickly
  • All the benefits of distributed tracing applied to your end-user monitoring

Requirements and compatibility

This feature reports AJAX requests (Fetch and XHR) that occur during a browser interaction. By default, only single-origin requests are monitored unless cross-origin resource sharing is enabled.

Make sure you have the necessary minimum versions for your browser and APM agents:

Enable distributed tracing

To enable distributed tracing for browser monitoring:

  1. Make sure you meet requirements.
  2. Go to one.newrelic.com, and click Browser, then select an app, then on the left side, click Application settings.
  3. Ensure the Distributed tracing toggle is on. By default, for agent version 1173 and above, the newrelic, traceparent, and tracestate headers will be added to all same-origin AJAX requests.
  4. Optional: If all of your services are configured to use the w3c trace context headers, you can choose to exclude the newrelic, traceparent, and tracestate headers from requests.
  5. Optional: Enable cross-origin resource sharing.
  6. Redeploy the browser monitoring agent (either restarting the associated APM agent or updating the copy/paste browser installation).
  7. If you have some apps or services that are downstream from your browser app that use the advanced option Infinite Tracing, see these setup steps.

Enable Infinite Tracing

If your browser apps have some downstream services that use the advanced type of distributed tracing called Infinite Tracing, you should enable this feature for your browser apps. This ensures that your root span (the initiating browser app) is included in the rest of the spans tracked by Infinite Tracing.

To set up Infinite Tracing:

  1. Complete the steps above to enable distributed tracing.
  2. Go to our Infinite Tracing documentation for steps to create a trace observer and to select which apps (data sources) should send trace spans to the Infinite Tracing trace observer.

Enable cross-origin resource sharing (CORS)

If you have AJAX requests that need resources from different origins, you can enable cross-origin resource sharing (CORS). By default, distributed tracing for cross-origin requests is not enabled because of browser CORS security restrictions: Distributed tracing is implemented by adding a custom HTTP headers (newrelic, traceparent, and tracestate) to outgoing AJAX requests, and browsers typically do not allow custom headers on cross-origin requests.

With the release of agent version 1173, we now support the w3c trace context headers (traceparent and tracestate) so these should also be allowed in your configuration.

There are two separate configurations required to enable cross-origin distributed tracing:

  1. Configure the service on the different origin to accept the newrelic custom header
  2. Configure browser monitoring to include the target origin in distributed tracing

Our step-by-step instructions provide key concepts and steps to enable this feature, but if you need more background about how cross-origin resource sharing works, we recommend this Mozilla developer document.

Risks and mitigations


Cross-origin resource sharing can expose you to a high level of risk if the services on the different origins are not configured correctly. The AJAX requests will likely return an error, resulting in a variety of failures, including:

  • Resources failing to load (for example, images and key content)

  • Login failures

  • Entire site outages (depending on type of requests enabled)

    By enabling this cross-origin resource sharing feature, you are acknowledging the following:

  • You understand that this feature is optional and not mandatory.

  • You understand the steps you need to take in order to enable this feature for your services and your domains.

  • You understand that if you do not properly configure your services prior to deployment (including but not limited to configuring your services on your domains to accept custom headers) portions or all of your website will likely malfunction.

  • You understand that New Relic is neither responsible nor liable for errors or issues related to your misconfiguration of servers or services.

  • You fully and solely accept the risks and wish to proceed.

The best way to minimize your risk is to ensure you fully understand the process and to try it first in a test environment. Before reading the step-by-step instructions, it may help to first read this overview of the process:

To use distributed tracing with cross-origin resources, you populate a list of approved cross-origin resources in New Relic, and then we automatically send the following custom headers to those resources: newrelic, traceparent, and tracestate. For this process to work, you must first ensure that someone has configured the services on the other origins to accept this custom header.

Cross-origin resource sharing uses a variety of HTTP headers (both in the request and response). The header that specifically applies to New Relic is the Access-Control-Allow-Headers response header, which can include newrelic, traceparent, tracestate, or newrelic, traceparent, tracestate in its value depending on what tracing strategies you enabled in your APM-monitored application. You must configure your server to return this CORS header in its response. Example:

Access-Control-Allow-Headers: newrelic, traceparent, tracestate


New Relic cannot perform any validation to ensure the services on the other origins were configured correctly. If you're unsure about how to allow these headers, do not add cross-origin resources to the approved list in the New Relic UI.

Enable cross-origin resource sharing


You should always try enabling CORS in a test environment before setting it up in production.

To enable cross-origin resource sharing:

  1. Confirm that the services on the other origins are configured to accept the newrelic header using: Access-Control-Allow-Headers: newrelic, traceparent, tracestate (for details, see Risks and mitigations).

  2. Confirm that you meet the Browser monitoring requirements.

  3. Make sure you are in one.newrelic.com, and click Browser > (select an app) > Application settings.

  4. Turn on the Distributed tracing toggle if it's not already enabled.

  5. Turn on the Cross-origin resource sharing (CORS) toggle.

  6. Under Cross-origin resource sharing (CORS), add cross-origin resources to the approved list.


    Valid cross-origin resources must include:

    • The prefix http:// or https://

    • The domain name

      The port number is not required unless it differs from the default for HTTP (port 80) or HTTPS (port 443).

  7. Select Save application settings to update the agent configuration.

  8. Redeploy the browser agent (either restarting the associated APM agent or updating the copy/paste browser installation).

Find data

Tips for finding and querying data:

  • You can find end-user-originating traces in any New Relic One distributed tracing UI.
  • In the distributed tracing UI, end-user spans are indicated with the New Relic distributed tracing browser span icon icon.
  • To see a span's attributes, select a span in the UI.
  • Spans are reported as Span data, and can be queried in New Relic.
  • Query tips:
    • Query by browser app name by setting browserApp.name to the browser app name.
    • Query for traces containing at least one browser app span with browserApp.name is not null.
    • Query for traces containing at least one back-end app with appName is not null.
    • Query for traces containing both browser and back-end spans by combining the two previous conditions.


If you don't see end-user spans, or are having other distributed tracing issues, see Troubleshooting.

Create issueEdit page
Copyright © 2022 New Relic Inc.