SPA data collection

This document explains how browser collects and stores your asynchronous single page app (SPA) data. This will give you a better understanding of the SPA data you see in the browser UI. This will also help you more easily add custom monitoring with the SPA API.

Browser interactions

At the heart of SPA monitoring is the concept of the browser interaction. New Relic defines a browser interaction as anything that occurs in the app user's browser; for example:

• A user interaction that leads to a page load or route change
• A scheduled, dynamic update to an app's widget

A browser interaction includes not just the initial triggering event, but also the activity caused by that event, such as AJAX requests and both synchronous and asynchronous JavaScript. By tracking not just the cause but also the effects of a browser interaction, we help you understand how users experience your application's views and route changes.

All apps are different and have different monitoring needs. That's why we include default monitoring as well as the ability to set up custom monitoring for any browser interactions you choose.

Types of SPA data reporting

Three major categories of single page app data can be reported to New Relic:

• Initial page loads
• Route changes
• Custom browser interactions created via the SPA API

Each of these creates a BrowserInteraction event. If one or more AJAX requests are part of an interaction, then associated AjaxRequest events are also created. These events and their attributes can be queried in the query builder.

Initial page loads

An initial page load is a traditional URL change, stemming from a complete load or reload of a URL. This is indicated in the browser when a page load event fires (the window.onload event). Initial page loads appear along with route changes in the browser UI.

Route changes

SPA users experience dynamic route changes in a similar way to page loads. Visitors to a site or app generally do not care how a new view was delivered; they simply know that when they perform an action, a new view appears. For this reason, we treat route changes in a similar way to page loads in the UI.

In order to optimally monitor single page applications, we start monitoring many browser interactions that could theoretically lead to route changes.

• If these interactions do not lead to route changes, browser initiates monitoring but then discards them.
• If these interactions do lead to a route change, browser saves the interaction sequence as a BrowserInteraction event, including information about both synchronous and asynchronous activity.

An interaction is considered a route change and saved as a BrowserInteraction event when one of the following occurs:

• The URL hash changes (usually using window.location.hash).
• A popstate event fires during a callback associated with an interaction.
• A pushState or replaceState API is called.

Route changes appear along with initial page loads in the browser UI.

We receive and save hash fragments from route change URLs. If you use hashes to pass private or sensitive data, that data may be visible to your New Relic account users. For more information about data collection and reporting, see Security for browser.

Custom monitoring

You can use the SPA API to set up custom monitoring of browser interactions that are not monitored by default. You can also use the API to disable default monitoring.

Custom events are saved as BrowserInteraction events and have the following attributes:

• The category attribute will have the value Custom.
• The trigger attribute will have the value api. (This is the default value but can be changed with the API.)

Difference from traditional page load timing

To provide optimized data for single page app monitoring, we measure page load timing in a new way: by wrapping low level browser functions, both synchronous and asynchronous. This gives a fuller depiction of how long it takes to complete the changes required for a new view.

This is different from the traditional method for page load timing. Traditional page load timing uses the firing of the window.onload event to determine when a page is loaded. This is not an optimal way to measure view change timing because web apps often have asynchronous code that runs for a significant amount of time after the window.onload event occurs.

The traditional window.onload page load timing still appears on the SPA Page views page. When you select a specific page load event, Window onload appears as a red line in the page load time chart. You can also select Switch to standard page views to return to traditional load timing displays.

Timers

The agent monitors all asynchronous calls, including timers. Timers with durations shorter than one second are wrapped. Timers longer than one second are not wrapped because usually they are meant for non-web transactions, such as background work or polling that is unrelated to a user interaction.

Events and attributes

We save browser interactions that lead to route changes and page loads as BrowserInteraction events, and AJAX requests as AjaxRequest events. You can query these events in the query builder.