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 this feature
- Enable distributed tracing
- Enable cross-origin resource sharing (CORS)
- Find and query data
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
Make sure you have the necessary minimum versions for your browser and APM agents:
APM agent versions:
To enable distributed tracing for browser monitoring:
- Make sure you meet requirements.
- Go to one.newrelic.com, and click Browser, then select an app, then on the left side, click Application settings.
- Ensure the Distributed tracing toggle is on. By default, for agent version 1173 and above, the
tracestateheaders will be added to all same-origin AJAX requests.
- Optional: If all of your services are configured to use the w3c trace context headers, you can choose to exclude the
tracestateheaders from requests.
- Optional: Enable cross-origin resource sharing.
- Redeploy the browser monitoring agent (either restarting the associated APM agent or updating the copy/paste browser installation).
- 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.
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:
- Complete the steps above to enable distributed tracing.
- 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.
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 (
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 (
tracestate) so these should also be allowed in your configuration.
There are two separate configurations required to enable cross-origin distributed tracing:
- Configure the service on the different origin to accept the
- 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.
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)
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:
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
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.
You should 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
Access-Control-Allow-Headers: newrelic, traceparent, tracestate(for details, see Risks and mitigations).
Confirm that you meet the Browser monitoring requirements.
Make sure you are in one.newrelic.com, and click Browser > (select an app) > 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.
Valid cross-origin resources must include:
The domain name
The port number is not required unless it differs from 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).
Tips for finding and querying data:
- You can find end-user-originating traces in any New Relic distributed tracing UI.
- 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.
- Spans are reported as
Spandata, and can be queried in New Relic.
- Query tips:
- Query by browser app name by setting
browserApp.nameto 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.
- Query by browser app name by setting
If you don't see end-user spans, or are having other distributed tracing issues, see Troubleshooting.