Skip to content

JavaScript API

Jump to bottom
John Riviello edited this page May 24, 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 and High Resolution Time 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 method, 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 both 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 HighRes duration from the time the HTML Document first starts loading instead of the 'navigationStart' attribute (which is the starting point for a DOMHighResTimeStamp). This code will also work with browsers that do not support High Resolution Time (it just falls back to the DOMTimeStamp mark).

// 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 delta:", surfnperf.getMark('foo', 'highRes') -
Performance.getMark('pageStart', 'highRes'));

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 the PerformanceTiming interface for the browsers that support it (unsupported browsers fall back to the 'pageStart' mark). However, since it does not use DOMHighResTimeStamp marks, you don't get the benefits High Resolution Time provides.

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

// set a variable to the 'responseEnd' Navigation Timing mark if the browser supports it,
// otherwise use the 'pageStart' mark we manually set in the <head>
var pageStart = Performance.getTimingMark('responseEnd') || Performance.getMark('pageStart', 'DOM');

// console.log the difference between that significant event and responseEnd||pageStart
console.log("Page Start to foo delta:", surfnperf.getMark('foo', 'DOM') -
pageStart);

Duration from the page load event to a specific event

// 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 foo delta:", surfnperf.getMark('bar') -
surfnperf.getTimingMark('loadEventEnd', 'HighRes'));

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');

Clear the specific event data

surfnperf.resetEvent('baz');

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

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