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, otherwise called a soft navigation, as the following sequence of events, drawing from Google's heuristics:

An user interaction occurs. We look specifically for click, keydown or submit events. The popstate event from the History API will also start an interaction.
The URL changes in any way, whether it's the path or hash.
Any changes, including to node attributes or text, occurs anywhere on the document DOM tree.

Following these steps, browser interactions are considered finished on the next repaint frame. They will also associate XHR and fetch requests started within their span. v2.1 introduced another step:

For SPA version 2.1 and later, the monitor checks for long-running callbacks for a maximum of 5 seconds. If a long-running callback is identified, the system extends the current interaction and reruns the monitor.

Interactions will fully conclude when there is a 5-second period without any long tasks. During the extension period leading up to the end of the last observed long task, any AjaxRequest and JavascriptError that occur will also be associated with the interaction. Importantly, the duration of the interaction will not include the final 5 seconds of inactivity.

Note that step four may be short-circuited or bypassed in certain scenarios.

Tip

The popstate event trigger is managed uniquely compared to other UI event triggers due to its specific behavior in browsers. When a popstate event occurs within 500 milliseconds after another UI event like a click, it will be merged into the existing interaction initiated by that event, without changing the interaction's original trigger (e.g., 'click'). However, two consecutive popstate events will never be merged in this manner.

Interactions with popstate as their trigger typically originate from browser actions, such as using the back or forward button, or from code-related actions like programmatically changing the URL.

Types of SPA data reporting

@@ -39,54 +38,39 @@ Three major categories of single page app data can be reported to New Relic:

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.

Important

Default or non-custom interactions do not wait for network requests to complete. They are associated with interactions on an as-is basis, meaning that only requests completed before the interaction is harvested by the scheduler are tied to it. If a network request has a slow or long duration and starts as part of an interaction, it may fall outside this time window and not be associated with the interaction.

Alternatively, you can manually extend the duration of an interaction to ensure it remains open until any important network request returns by using the API.

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) and also called a hard navigation. 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 any interaction that could theoretically lead to route changes.

If these interactions do not complete the heuristic steps defined above, agent initiates monitoring but then discards them.
If these interactions do follow all steps, agent saves the sequence as a completed BrowserInteraction event.

An interaction is considered a route change and saved as a BrowserInteraction event if the URL changes between the start and end. URL changes are tracked in two ways:

The popstate event. Changing the url programmatically, such as setting window.location.hash will trigger this event.
pushState or replaceState is called. SPAs commonly use these History API methods to update the URL.

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

Note that the agent reports 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

All apps are different and have different monitoring needs. You can use the SPA API to customize your browser interactions or self define the way it's captured.

Custom events are saved as BrowserInteraction events and have the following difference in 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.)

The API allows you to dictate when to start and stop such custom interaction, if the above heuristic does not fit your user base or app.

Events and attributes

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

Browser interactions .css-21sua1{background:none;border:none;width:0;padding:0;}