Browser data in distributed tracing

If you use New Relic to monitor end-user browser activity, you can take advantage of distributed tracing to see browser-side traces that originate from the end-user experience.

Trace activity from front end to back end

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

Spot latencies, errors, and anomalies in the browser or network more easily.
Resolve customer-facing problems more quickly.
Apply all the benefits of distributed tracing to your end-user monitoring.

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.

Browser and APM versions

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

Browser monitoring:

For distributed tracing: Browser Pro+SPA agent with distributed tracing enabled and Browser agent version 1153 or higher
For cross-origin resource sharing: Browser agent version 1158 or higher
For W3C trace context support: Browser agent version 1173 or higher

APM:

C SDK 1.3 or higher
Java 5.9.0 or higher
PHP 9.4.0 or higher
Other APM agent version requirements

Enable distributed tracing

By default, for agent version 1173 and higher, the newrelic, traceparent, and tracestate headers will be added to all same-origin AJAX requests. (If you exclude them, no headers will be sent.) For more information, see our documentation about W3C trace context headers.

To enable distributed tracing for browser monitoring:

Make sure your browser monitoring agent and APM agent are compatible with distributed tracing. Update to the most recent version if applicable.
Go to one.newrelic.com, and click Browser. Select an app, then click Application settings.
Turn on the Distributed tracing toggle.
Optional: Enable cross-origin resource sharing.
Redeploy the browser monitoring agent, either by restarting the associated APM agent or by updating the copy/paste browser installation.
If you have apps or services that are downstream from your browser app and they use Infinite Tracing, complete the setup steps for Infinite Tracing.

W3C trace context headers

With the release of browser monitoring agent version 1173, we support the W3C trace context headers (traceparent and tracestate), so be sure to allow them in your configuration. W3C trace context defines a pair of standardized context HTTP headers that serve to propagate context correlation information between services:

A traceparent header contains the data elements that every distributed tracing model requires to define and propagate context: a trace ID, a parent ID, and a sample flag.
A tracestate header holds vendor-specific, contextual data, typically in order to support additional functionality or optimizations associated with a particular tracing tool.

For more information about W3C trace context, see our blog post.

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 custom HTTP headers (newrelic, traceparent, and tracestate) 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:

Configure the service on the different origin to accept the newrelic custom header.
Configure browser monitoring in your Application settings to include the target origin in distributed tracing.

This section provides key concepts and steps to enable and configure CORS. If you need more background about how cross-origin resource sharing works, we recommend this Mozilla developer document.

Caution

As explained in the following section, cross-origin resource sharing can expose you to a high level of risk if the services on the different origins are not configured correctly. We recommend that you read the next three sections sequentially.

If services on 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 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. We recommend that you read the following overview of the CORS process before continuing with the CORS configuration procedure.

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 the 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

Important

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.

Caution

Always try enabling CORS in a test environment before setting it up in production

To enable cross-origin resource sharing:

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.
Make sure your browser monitoring agent and APM agent are compatible with distributed tracing for CORS. Update to the most recent version if applicable.
Go to one.newrelic.com, and click Browser. Select an app, then click Application settings.
Turn on the Distributed tracing toggle if it's not already enabled.
Turn on the Cross-origin resource sharing (CORS) toggle.
Under Cross-origin resource sharing (CORS), add cross-origin resources to the approved list. Make sure that your cross-origin resources include the prefix http:// or https:// and the domain name. Include your port number if it is different than the default for HTTP (port 80) or HTTPS (port 443).
Select Save application settings to update the agent configuration.
Redeploy the browser agent (either restarting the associated APM agent or updating the copy/paste browser installation).

Enable Infinite Tracing

We offer a tail-based distributed tracing feature called Infinite Tracing. If your browser apps have downstream services, be sure to enable it. 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:

Complete the steps to enable distributed tracing.
Go to our Infinite Tracing documentation, then follow the steps to create a trace observer and to select which apps (data sources) you want to send trace spans to the Infinite Tracing trace observer.

Explore your trace data

Here are some tips for finding and querying your trace data in New Relic.

If you want to...	Do this...
Examine traces originating from end-user experience	Go to any distributed tracing page in the New Relic UI.
View end-user spans	In the distributed tracing UI, end-user spans are indicated with the icon. To see a span's attributes, select a span in the UI.
Query span data	Spans are reported as `Span` data. You can query span data in New Relic. For example: Query by browser app name by setting `browserApp.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 want to...

Do this...

Examine traces originating from end-user experience

Go to any distributed tracing page in the New Relic UI.

View end-user spans

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.

Query span data

Spans are reported as Span data. You can query span data in New Relic. For example:

Query by browser app name by setting browserApp.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 our troubleshooting documentation.

Trace activity from front end to back end

Browser and APM versions

Enable distributed tracing

W3C trace context headers

Enable cross-origin resource sharing (CORS)

Caution

Important: Read about CORS risks and mitigation before you begin

Overview of CORS process

Important

Configure CORS

Caution

Enable Infinite Tracing

Explore your trace data

Troubleshooting