Browser data in distributed tracing

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

Browser data is available in standard distributed tracing only.

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 minimum versions for your Browser, APM, and APM agents:

Enable distributed tracing

To enable distributed tracing for New Relic Browser:

  1. Make sure you meet requirements, including having:
  2. Go to rpm.newrelic.com/browser > (select an app) > Settings > Application settings.
  3. Turn on the Distributed tracing toggle.
  4. Optional: Enable cross-origin resource sharing.
  5. Redeploy the Browser agent (either restarting the associated APM agent or updating the copy/paste Browser installation).

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: New Relic distributed tracing is implemented by adding a custom HTTP header (newrelic) to outgoing AJAX requests, and browsers typically do not allow custom headers on cross-origin requests.

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 New Relic Browser 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.

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 New Relic 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 header to those resources: newrelic. 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 needs to include newrelic in its value. You must configure your server to return this CORS header in its response. Example:

Access-Control-Allow-Headers: newrelic

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.

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 (for details, see Risks and mitigations).
  2. Confirm that you meet the New Relic Browser requirements.
  3. Make sure you are in rpm.newrelic.com/browser > (select an app) > Settings > 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 trace 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.

Troubleshooting

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

For more help

Recommendations for learning more: