Relic Solution: Troubleshooting Distributed Tracing for Browser

Getting Distributed Tracing working for your Browser monitored application can be a tricky business, and missed steps can cause anything from missing trace data to failed requests.

However, if you’ve tried to set it up but you’re not seeing the data you expect, there’s a good chance it’s due to one of a small number of reasons. To help you investigate, I’ve put together this list of troubleshooting steps.

Note that this is not intended to be a complete list of all the ways in which Browser Distributed Tracing might not work! These are just some of the most common issues we see in support tickets. If you’ve completed all these steps but are still not seeing the data you expect, your next step should probably be to reach out for further assistance.

Okay, let’s get started!

1. Does your application meet the basic requirements for Browser Distributed Tracing?

If you want to see front to back traces you must have a Browser application being monitored with the SPA agent and DT enabled, and it must be making requests to an APM application that also has Distributed Tracing enabled.

You also need to make sure that you’re using the correct version of the SPA agent as different features have been introduced over time. For example, Distributed Tracing first came to Browser with agent version 1153, tracing for cross-origin requests were added in version 1158, and support for W3C trace context was added in version 1173.

Note: APM injection of the Browser agent is not required to use the distributed tracing feature.


2. Is the application generating AjaxRequest event data?

The Browser Distributed Tracing feature traces requests (Fetch and XHR) that occur during a browser interaction. These are the requests that get recorded as AjaxRequest event data. It’s worth a quick query to make sure that your application is reporting these events before you get deeper into the more complicated troubleshooting. If it’s not, you should make sure that you have the SPA agent script installed and that the requests are happening during the initial page load or a route change, or as part of a custom interaction.


3. Has Browser Distributed Tracing been enabled?

The Distributed Tracing is not enabled by default for Browser applications. You must take extra steps to turn it on. To check, look at your application’s settings screen. You will be able to see here whether the feature has been enabled.

If the application was instrumented using the copy and paste method, you will also need to make sure that you save these new settings, get the updated loader script, and update the script in your application. This is because the script will now contain some new components that are essential to this feature.

Note: I’m finding that many customers have created their own application configuration block so that they can dynamically change which application ID the application is reporting to. By configuration block, I mean the section highlighted in red here:

You can do this, but be aware that the Browser Distributed Tracing feature requires several new pieces of information like a trustKey and accountID that weren’t used in older versions of the agent. So, if created your own configuration script, make sure that you’ve updated it with this new information (you can find it all in the script we provide in your application settings screen). Without these, Browser Distributed Tracing will not work.


4. Are the requests cross-origin?

We get a lot of questions about this. If the request you want to be traced starts on one domain and goes to an endpoint on a different domain, it’s a cross-origin request and you need to enable CORS sharing in order for Browser Distributed Tracing to generate traces for them.

Not sure if they’re cross-origin? Try a query like this:

`SELECT count(*) from AjaxRequest where appName like 'APPNAME'  limit 100 facet pageUrl, requestUrl`

(If you want to figure out if a specific request is cross-origin, add an additional WHERE clause with that requestUrl to the query to zero in on that subset of your data.)

If the pageUrl and the requestUrl have different domains, then this is a cross-origin request.


5. Has CORS been correctly enabled and configured?

If in step 4 you determined that the requests you want to be traced are cross-origin, you still have a little more work to do to make Browser Distributed Tracing work.

Simply enabling CORS in the application settings isn’t enough - we will only add the required headers to requests being made to the origins you specify in your settings. You need to make sure you have:

  1. Configured your destination origin to accept our headers. If you don’t do this, the Distributed Tracing feature will likely cause your requests to fail.
  2. Added the destination origin(s) for your cross-origin requests where indicated in the application settings screen.
  3. Saved the changes and generated an updated script that will include a list of the specified origins.
  4. Updated the script in your application (if you are using the copy and paste method of installation). If you’re using APM injection for installation you can skip this step, the updated script will automatically be injected once you save the new settings.

6. Is our header being injected?

If you’ve completed steps 1 through 5 correctly, we should be injecting a header into the request. To verify this:

  1. Open up a page in the application that is making the request you want to check.
  2. Go to the network tab in the developer console, and find one of these requests.
  3. Click the request to view the details, look at the Request Headers section, and check to see if there’s an entry in Request Headers labeled either newrelic (our original, proprietary header) or tracestate and traceparent (W3C Trace Context headers), depending on which type of headers you’ve chosen to use.


That’s it!

If you’ve completed all of the above successfully, you should now be able to find Span events originating in the Browser application.



I’m trying to get distributed tracing for browser working in a situation where a browser app is invoking a lambda function behind AWS API Gateway.

When reading this piece this particular section stood out to me:

Does this mean this feature only works for browser to APM monitoring and does not work for lambda monitoring or is lambda monitoring “close enough” to APM monitoring that this feature should also work in that context?

Hi @walter2, I would advise that the best way of approaching this is to apply everything said here specifically to browser to APM.

You can read more about enabling distributed tracing for lambda here

To Note, for step Number #2, with the browser agent release v1211 in Oct. 2021, all requests will be captured as Spans. Previously, Span events were generated only for XHR/fetch requests that were part of a route change.

Please see release notes here: