Skip to content

JavaScript API

Jump to bottom
John Riviello edited this page May 26, 2014 · 10 revisions

JavaScript API

Introduction

This micro-library allows you to gather performance timing data for your webapps and websites by exposing an easy to use API leveraging Navigation Timing, High Resolution Time and User Timing for the browsers that support them. The intended use is to gather the data using the API and then log it to your server for later analysis. Since the actual logging is most likely application-specific, it is not part of this library. However, since Underscore is a dependency, you can easily extend this library to add on your own functions, including those for logging.

Usage through sample code

Navigation Timing Page Load Timing Data methods:

surfnperf.getNetworkLatency(); // fetchStart to responseEnd
surfnperf.getProcessingLoadTime(); // responseEnd (or pageStart for older browsers) to loadEventEnd
surfnperf.getFullRequestLoadTime(); // navigationStart to loadEventEnd

// Note that if you want to use the above methods as soon as the page load event fires,
// you'll have to wrap that in a setTimeout call so that the load event can fire first:
$(window).load(function() {
  setTimeout(function() {
    console.log(
      'Network Latency:', surfnperf.getNetworkLatency(),
      'Processing:', surfnperf.getProcessingLoadTime(),
      'Full Request:', surfnperf.getFullRequestLoadTime()
    );
  }, 0);
});

Custom Key/Value Data Store

// store a custom key/value
surfnperf.setCustom('customKey', 'custom value');

// retrieve the custom key's value
surfnperf.getCustom('customKey');

Duration from the 'pageStart' mark to a specific event

The 'pageStart' mark is set as User Timing mark, a DOMHighResTimeStamp mark, and a DOMTimeStamp mark in the <head>. This mark is set between the 'domLoading' and 'domInteractive' attributes of the PerformanceTiming interface. You may want to use this mark if you want to calculate a duration from the time the HTML Document first starts loading and have that starting point be the same across all browsers regardless of their supported features.

// mark a spot in time as significant
surfnperf.mark('foo');

// console.log the difference between that significant event and the pageStart mark
console.log("Page Start to foo duration:", surfnperf.duration('pageStart', 'foo'));

Duration from the time the page response completed to a specific event

This is similar to the "Duration from the 'pageStart' mark to a specific event" above, but in this case, it uses the exact 'responseEnd' attribute of Navigation Timing for the browsers that support it. Unsupported browsers fall back to the 'pageStart' mark for all Navigation Timing properties between 'navigationStart' and 'domLoading'.

// mark a spot in time as significant
surfnperf.mark('foo');

console.log("responseEnd to foo duration:", surfnperf.duration('responseEnd','foo'));

Duration from the page load event to a specific event

Note that for browsers that do not support Navigation Timing, 'loadEventEnd' is used for all Navigation Timing properties between ''domInteractive' and 'loadEventEnd'.

// mark a spot in time as significant
surfnperf.mark('bar');

// console.log the difference between that significant event and when the loadEventEnd event fired
console.log("loadEventEnd to bar duration:", surfnperf.duration('loadEventEnd','bar'));

Duration of a specific event

// mark the start of some significant process
surfnperf.eventStart('baz');
// mark the end of some significant process
surfnperf.eventEnd('baz');
// get the duration of that significant process
surfnperf.eventDuration('baz');

Sub-millisecond durations

For browsers that support High Resolution Time, you can retrieve durations with sub-millisecond accuracy by passing a 'decimalPlaces' option

surfnperf.duration('loadEventEnd','bar',{decimalPlaces:5});
surfnperf.eventDuration('baz',{decimalPlaces:10});

Clear the specific event data

surfnperf.resetEvent('baz');

Duration of a specific event (e.g. AJAX call using Backbone fetch) with additional data

var collection = new Backbone.Collection;
collection.url = '/get-data/';

// mark the start of the AJAX call
surfnperf.eventStart('getData');
collection.fetch({
  success: function(collection) {
    // mark the end of the AJAX call, set its status to 'success' and the number of items returned as 'items'
    surfnperf.eventEnd('getData', {status:'success', items: collection.length});
  },
  error: function() {
    // mark the end of the AJAX call, set its status to 'error'
    surfnperf.eventEnd('getData', {status:'error'});
  },
});

// And then when you're ready, retrieve the data
surfnperf.eventDuration('getData', {decimalPlaces:2}); // duration of AJAX call, accurate to 2 decimal places
surfnperf.getEventData('getData', 'status'); // status of AJAX call
surfnperf.getEventData('getData', 'items'); // number of items returned
Clone this wiki locally