OSS Boomerang

BOOMR.plugins. SPA

Enables Single Page App (SPA) performance monitoring.

Note: The SPA plugin requires the BOOMR.plugins.AutoXHR plugin to be loaded before SPA, and one of the following SPA plugins to work:

  • BOOMR.plugins.Angular
  • BOOMR.plugins.Backbone
  • BOOMR.plugins.Ember
  • BOOMR.plugins.History (React and all other SPA support)

You also need to disable autorun when enabling SPA support.

If you are not using a SPA framework but rely mostly on XMLHttpRequests to build your site, you might be able to skip the SPA plugins and just enable the BOOMR.plugins.AutoXHR plugin to measure your site.

For information on how to include this plugin, see the Building tutorial.

Approach

Boomerang monitors Single Page App (SPA) navigations differently than how it monitors navigations on traditional websites.

On traditional websites, the browser completes a full navigation for every page. During this navigation, the browser requests the page's HTML, JavaScript, CSS, etc., from the server, and builds the page from these components. Boomerang monitors this entire process.

On SPA websites, only the first page that the visitor loads is a full navigation. All subsequent navigations are handled by the SPA framework itself (i.e. AngularJS), where they dynamically pull in the content they need to render the new page. This is done without executing a full navigation from the browser's point of view.

Boomerang was designed for traditional websites, where a full navigation occurs on each page load. During the navigation, Boomerang tracks the performance characteristics of the entire page load experience. However, for SPA websites, only the first page triggers a full navigation. Thus, without any additional help, Boomerang will not track any subsequent interactions on SPA websites.

To give visibility into SPA website navigations, there are several Boomerang plugins available for SPA frameworks, such as AngularJS, Ember.js and Backbone.js. When these plugins are enabled, Boomerang is able to track all of the SPA navigations beyond the first, initial navigation.

To do so, the Boomerang SPA plugins listen for several life cycle events from the framework, such as AngularJS's $routeChangeStart. Once it gets notified of these events, the Boomerang SPA plugins start monitoring the page's markup (DOM) for changes. If any of these changes trigger a download, such as a XHR, image, CSS, or JavaScript, then the Boomerang SPA plugins monitor those resources as well. Only once all of these new resources have been fetched do the Boomerang SPA plugins consider the SPA navigation complete.

For a further explanation of the challenges of measuring SPAs, see our slides or our talk.

Hard and Soft Navigations

  • A SPA Hard Navigation is always the first navigation to the site, plus any of the work required to build the initial view.
    • The Hard Navigation will track at least the length of onload, but may also include the additional time required to load the framework (for example, Angular) and the first view.
    • A SPA site will only have a single SPA Hard Navigation, no "Page Load" beacons.
    • The http.initiator type is spa_hard
  • A SPA Soft Navigation is any navigation after the Hard Navigation.
    • A soft navigation is an "in-page" navigation where the view changes, but the browser does not actually fully navigate.
    • A SPA site could have zero through many Soft Navigations
    • The http.initiator type is spa

Navigation Timestamps

Hard Navigations

The length of a Hard Navigation is calculated from the beginning of the browser navigation (e.g. navigationStart from NavigationTiming) through when the last critical resource has been fetched for the page.

Critical resources include Images, IFRAMEs, CSS and Scripts.

Soft Navigations

The length of a Soft Navigation is calculated from the beginning of the route change event (e.g. when the user clicked somewhere to change the view) through when the last critical resource has been fetched for the page.

Front-End vs. Back-End Time

For SPA navigations, the Back End time (t_resp) is calculated as any period where a XHR or Script tag was being fetched.

The Front End time (t_page) is calculated by taking the total SPA Page Load time (t_done) minus Back End time (t_resp).

Beacon Parameters

  • http.initiator
    • spa_hard for Hard Navigations
    • spa for Soft Navigations

Methods

current_spa_nav()

Determine the current SPA navigation type (spa or spa_hard)

Returns:

Type: string

SPA beacon type

hook(hadRouteChange [, options])

Called by a framework when it has hooked into the target SPA

Parameters:

Name Type Argument Description
hadRouteChange boolean

True if a route change has already fired
options object <optional>

Additional options

Properties
Name Type Argument Description
routeFilter BOOMR.plugins.SPA.spaRouteFilter <optional>

Route filter
routeChangeWaitFilter BOOMR.plugins.SPA.spaRouteChangeWaitFilter <optional>

Route change wait filter
routeChangeWaitFilterHardNavs boolean <optional>

Whether to apply wait filter on hard navs
disableHardNav boolean <optional>

Disable sending SPA hard beacons

Returns:

BOOMR.plugins.SPA The SPA plugin for chaining

init(config)

Called to initialize the plugin via BOOMR.init()

Parameters:

Name Type Description
config object

Configuration

is_complete()

Determines if the plugin is complete

Returns:

Type: boolean

True if the plugin is complete

isSpaNavInProgress()

Determines if a SPA navigation is in progress

last_location(url)

Called by a framework when the location has changed to the specified URL. This should be called prior to route_change() to use the specified URL.

Parameters:

Name Type Description
url string

URL

markNavigationComplete()

Marks the current navigation as complete and sends a beacon. The spa soft navigation will not wait for other nodes in progress

onLoadSpaHardMissed()

Fired when onload happens (or immediately if onload has already fired) to monitor for additional resources for a SPA Hard navigation

register(pluginName)

Registers a framework with the SPA plugin

Parameters:

Name Type Description
pluginName string

Plugin name

route_change(onComplete, routeFilterArgs)

Called by a framework when a route change has started. The SPA plugin will begin monitoring downloadable resources to measure the SPA soft navigation.

Parameters:

Name Type Description
onComplete function

Called on completion
routeFilterArgs Array.<object>

Route Filter arguments array

supported_frameworks()

Gets a list of supported SPA frameworks

Returns:

Type: Array.<string>

List of supported frameworks

wait_complete()

Called by the SPA consumer if we have a routeChangeWaitFilter and are manually waiting for a custom event. The spa soft navigation will continue waiting for other nodes in progress

Type Definitions

spaRouteChangeWaitFilter(data)

Callback to let the SPA plugin know whether or not the end of monitoring of the current SPA soft route should be delayed until BOOMR.plugins.SPA.wait_complete is called.

If the callback returns false, the route will be monitored as normal.

Parameters:

Name Type Description
data object

Route data

Returns:

Type: boolean

true to wait until BOOMR.plugins.SPA.wait_complete is called.

spaRouteFilter(data)

Callback to let the SPA plugin know whether or not to monitor the current SPA soft route.

Any time a route is changed, if set, this callback will be executed with the current framework's route data.

If the callback returns false, the route will not be monitored.

Parameters:

Name Type Description
data object

Route data

Returns:

Type: boolean

true to monitor the current route