newrelic.interaction().createTracer(string NAME, function CALLBACK)
Times sub-components of a SPA interaction separately, including wait time and JS execution time.

Requirements

Requires New Relic Browser agent version nr-963 or higher.

Access to this feature depends on your subscription level. New Relic's single page app (SPA) monitoring is only available with New Relic Browser Pro.

Description

This method provides a way to time sub-components of a SPA interaction separately in New Relic 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 Insights. To view this timing information in New Relic Browser:

  1. From rpm.newrelic.com, select Browser > (selected SPA app) > Page views.
  2. From Page views, select a browser interaction, then select the Breakdowns tab.

The newrelic.interaction().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.

Parameters

Parameter Description

NAME

function

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

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

CALLBACK

function

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 newrelic.interaction().createTracer.

Return value(s)

This method ends the async time. It calls (and times) the callback that was passed into createTracer.

Example(s)

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:

newrelic
  .interaction()
  .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 New Relic 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.

In this example, 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).

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

Here's how createTracer could be used to accomplish this:

var wrappedCallback = newrelic
  .interaction()
  .createTracer('customSegment', doTheWork)

doAsyncWork(wrappedCallback)

function doTheWork() {
  // ... do your work ...
}

Here is the timeline of events:

[scald=5946:sdl_editor_representation]
Overview of tracer timing