• /
  • Log in

createTracer (browser SPA API)


newrelic.interaction().createTracer(string $name[, function $callback])

Times sub-components of a SPA interaction separately, including wait time and JS execution time.


Agent version nr-963 or higher.


This method provides a way to time sub-components of a SPA interaction separately in browser. Each sub-component will measure:

  • Wait time until callback is executed
  • JS execution time of callback once it is invoked

This method also can be used to bridge the asynchronous gap created by uninstrumented async methods.

If the current interaction is saved, New Relic will create a BrowserTiming event in New Relic One. To view this timing information in browser:

  1. Go to one.newrelic.com, click on Browser > (select a SPA app) > Page views.
  2. From Page views, select a browser interaction, then select the Breakdowns tab.

The createTracer() method returns a wrapped callback method, which you must invoke from your code. The returned wrapped callback will do three things when invoked:

  1. Records the end of the async portion of the custom tracer.
  2. Runs the original callback passed to createTracer() with the same arguments and context.
  3. Times the execution of the original callback.

A BrowserInteraction that runs createTracer() will create a BrowserTiming event. Any new XHRs or custom traces created during the callback will be included as part of the interaction.

An interaction will not be considered complete until all of its tracers finish. This is what allows tracers to wrap async functions that the browser agent does not handle by default.






Required. This will be used as the name of the tracer.

If you do not include a name, browser does not add a node to the interaction tree. The callback time will be attributed to the parent node.



Optional. A callback that contains the synchronous work to run at the end of the async work. To execute this callback, call the wrapper function returned using createTracer().

Return values

Returns a method that wraps the original callback. When this method is invoked, it calls the original callback and ends the async timing.


Create tracer

If you simply want to measure how long a particular JavaScript function call takes, you can pass the function to createTracer() as a callback. This immediately invokes the returned wrapper callback:

.createTracer('customSegment', function myCallback () {
// ... do your work ...

In this scenario, the resulting custom tracer will have a negligible async wait duration, as well as a synchronous duration equal to the execution time of myCallback().

Trace an uninstrumented asynchronous API

By default, the browser agent wraps many of the most common asynchronous functions (such as setTimeout()). However, there are some functions that are not handled automatically (for example, requestAnimationFrame()). In addition, some cases occur where causality cannot easily be determined (for example, a custom RPC implementation over websockets). For these cases, you can use createTracer() to make sure callbacks to these uninstrumented functions are considered part of the interaction.

Using createTracer() is not necessary for any async scheduling system based on async APIs that are wrapped natively by the browser agent, such as setTimeout(), setImmediate(), Promise(), fetch(), and XMLHttpRequest(). The async boundaries created by these APIs will be bridged automatically by the browser agent.

In the example code below, you have a function, doAsyncWork(), that accepts a callback and executes it asynchronously at some point in the future. You want to measure both the time between when you invoke doAsyncWork() and when the callback begins executing (the async wait time), and the time taken to run the callback (the synchronous callback time).

var wrappedCallback = newrelic
.createTracer('customSegment', doTheWork)
function doTheWork() {
// ... do your work ...

Here is a timeline of events for tracer timing:

SPA async timeline image

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.