Extend the JavaScript Agent for Single Page Applications (SPAs) in Browser RUM

On this page:

Out-of-the-box Browser RUM supports single page applications created using the AngularJS framework, but you can extend the JavaScript Agent to non-AngularJS frameworks using the JavaScript agent API.

The API allows you to report events to the agent so that that it can time the various parts of your virtual page loads and correlate Ajax calls to those page loads. You can also capture and report errors using this API.

Requirements for Extending JavaScript Agent for SPAs

Browsers must fully support CORS. Thus, because IE 9 and below only partially support CORS, the JavaScript Agent cannot be extended for SPAs. (Only IE 10 and IE Edge fully support CORS when not in compatibility mode.)
To extend the agent to non-AngularJS frameworks, the JavaScript Agent v4.2 or higher is required.

Notify the Agent of Events

Events are reported to the JavaScript agent (ADRUM) by calling the ADRUM.report method and passing in an event tracker object.

API	Description
ADRUM.report(tracker: eventTracker);	Notifies the agent of an event

Event Trackers

Events are reported to the agent using event trackers. There are three different kinds of event trackers:

VPageView: used to track the stages of a virtual page view
Ajax: used to track Ajax requests
Error: used to track errors

Common Properties

There are also two properties that are common to all tracker types

Gets or sets a URL
API Description
url(url?: string) Gets or sets a URL
Gets or sets the parent event identifier
API Description
parent(parent?: object) Gets or sets the parent event identifier

VPageView

The page view load flow. Most single page app frameworks follow a work flow similar to the one below, taken from Angular. You'll use our API to set timing marks to match the below workflow as closely as possible in your own single page app framework.

Based on the marks you set, AppDynamics derives the following key timing metrics. Marks should be called in the order in which they occur in the flow. The following table describes which marks used to calculate each metric.

Full Metric Name	Short Metric Name	How Calculated
End User Response Time (not used for waterfall UI)	PLT	virtualPageStart to virtualPageEnd
HTML Download Time	DDT	viewChangeStart to viewChangeEnd
HTML Download and DOM Building Time	DRT	viewChangeStart to viewDOMLoaded
DOM Building Time	DPT	viewChangeEnd to viewDOMLoaded
DOM Ready Time (used instead of PLT for waterfall UI)	DOM	viewChangeStart to viewDOMLoaded

Instantiate using ADRUM.events.VPageView().

API	Description
`start()`	Indicates when a virtual page starts. It automatically calls: startCorrelatingXhrs() markVirtualPageStart()
`end()`	Indicates when a virtual page ends. It automatically calls: stopCorrelatingXhrs() markVirtualPageEnd()
`startCorrelatingXhrs()`	Correlates the Ajax requests sent after this call with the virtual page view event. The last tracker calling this method wins. This method is called automatically in the VPageView constructor. When a VPageView is created, the AJAX requests made after that call are automatically correlated to that VPageView. Use this separate call only when you wish to set up manual correlation.
`stopCorrelatingXhrs()`	Stops correlating Ajax requests to the virtual page view event. Use this separate call only when you wish to set up manual correlation.
Setters	The default value for these is the time when the API is called.
`markViewChangeStart()`	Sets the view change start time.
`markViewChangeEnd()`	Sets the view change end time.
`markViewDOMLoaded()`	Sets the view DOM loaded time.
`markXhrRequestsCompleted()`	Sets the XHR requests completed time.
`markViewResourcesLoaded()`	Sets the view resources loaded time. This includes images, css files, and scripts.
`markVirtualPageStart()`	Sets the virtual page start time.
`markVirtualPageEnd()`	Sets the virtual page end time.
Getters
`getViewChangeStart()`	Gets the view change start time.
`getViewChangeEnd()`	Gets the view change end time.
`getViewDOMLoaded()`	Gets the view DOM loaded time.
`getXhrRequestsCompleted()`	Gets the XHR requests completed time.
`getViewResourcesLoaded()`	Gets the view resources loaded time.
`getVirtualPageStart()`	Gets the virtual page start time.
`getVirtualPageEnd()`	Gets the virtual page end time.

Ajax

For more details on what these metrics measure, see Browser RUM Metrics.

Instantiate using ADRUM.events.Ajax().

API	Description
Property Setters/Getters	Call this without a parameter to get the value and with a parameter to set the value.
`method(method?: string)`	Gets or sets the method ("GET" or "POST") of the Ajax.
Timing Setters	The default value for these is the time when the API is called.
`markSendTime(sendTime?: number)`	Sets the time the request is sent.
`markFirstByteTime(firstByteTime?: number)`	Sets First Byte Time.
`markRespAvailTime(respAvailTime?: number)`	Sets Response Available Time.
`markRespProcTime(RespProcTime?: number)`	Sets the time the response is completely processed.
Timing Getters
`getSendTime()`	Gets the time the request was sent.
`getFirstByteTime()`	Gets First Byte Time.
`getRespAvailTime()`	Gets Response Available Time
`getRespProcTime()`	Gets the time the response was completely processed.

Errors

Instantiate using ADRUM.events.Error().

API	Description
Property Setters/Getters	Call these without a parameter to get the value and with a parameter to set the value.
`msg(msg?: string)`	Gets or sets the error message.
`line(line?: number)`	Gets or sets the line number of source code where the error happened.

Ajax Correlation

Ajax requests can be correlated to virtual page views automatically or manually. When you create a VPageView tracker, startCorrelatingXhrs() is called automatically in the constructor, correlating any subsequent Ajax calls with that VPageView event. To set up manual correlation, call stopCorrelatingXhrs() to stop the automatic process and then call startCorrelatingXhrs() where you wish correlation to re-commence.

Sample Code

Report a custom Error event by passing properties via setters

var errorT = new ADRUM.events.Error();
errorT.msg('I am a custom error at line 100');
errorT.line(100);
ADRUM.report(errorT);

Report a custom Error event by passing properties via the constructor

var errorT = new ADRUM.events.Error({
msg: 'I am a custom error at line 100',
line: 100
});
ADRUM.report(errorT);

Report a custom Ajax event passing properties via setters

var ajaxT = new ADRUM.events.Ajax();
  
// set url
ajaxT.url('your xhr Url');
  
// mark timings
ajaxT.markSendTime(100);
ajaxT.markFirstByteTime(200);
ajaxT.markRespAvailTime(300);
ajaxT.markRespProcTime(400);
ADRUM.report(ajaxT);

Set Up Backbone SPA Monitoring

var AppRouter = Backbone.Router.extend({
    routes: {
        "wines/:id"         : "wineDetails"
    },
    wineDetails: function (id) {
        var vpView = new ADRUM.events.VPageView();
        vpView.markVirtualPageStart();
        // vpView.markViewChangeStart();
        var wine = new Wine({id: id});
        wine.fetch({success: function(){
            vpView.markXhrRequestsCompleted();
            $("#content").html(new WineView({model: wine}).el);
            vpView.markViewDOMLoaded();
            vpView.markVirtualPageEnd();
            ADRUM.report(vpView);
        }});
        this.headerView.selectMenuItem();
    }
});

Correlate Ajax requests wih VPageView Events

var vPageView = new ADRUM.events.VPageView({
    url: 'http://localhost/#virtualpage1',
});
 
vPageView.start();
 
// SPA view routing and HTML partials fetching
vPageView.markViewChangeStart()
// AJAX requests for the HTML partials are automatically correlated with the VPageView
...
vPageView.markViewChangeEnd();
 
// HTML partials inserted into Browser DOM tree
...
vPageView.markViewDOMLoaded();
 
// SPA HTML AJAX data fetching
// Data AJAX requests are automatically correlated with the VPageView
...
 
vPageView.markXhrRequestsCompleted();
 
// call this when ending a new virtual page
vPageView.end();
 
ADRUM.report(vPageView);

You can exclude certain Ajax calls from being monitored by configuring ADRUM itself. Before you invoke the adrum.js script at the top of your page, add lines similar to the following:

Exclude Ajax from VPageView using ADRUM configuration

window['adrum-config'] = {
  "spa": {
    "angular": {
      "vp": {
        "xhr": {
          "exclude": {
            "urls": [{
              "pattern": 'heartBeatAjax'
            }]
          }
        }
      }
    }
  }
}

Or you can exclude certain Ajax calls using the vPageView.stopCorrelatingXhrs() call, and then turning correlation back on with vPageView.startCorrelatingXhrs(), as in the following:

Exclude Ajax from VPageView event manually

var vPageView = new ADRUM.events.VPageView();
vPageView.stopCorrelatingXhrs();
  
var xhr = new XMLHttpRequest();
xhr.open('GET', '/heartBeatAjax');
xhr.send();
  
vPageView.startCorrelatingXhrs();