Surf-N-Perf

Micro-library for gathering frontend web page performance data.

Surf-N-Perf provides a simple to use API to gather User Timing and other important performance data in any browser.

Tired of typing window.performance.getEntriesByName('foo')[0].startTime; with your User Timing Polyfill?

With Surf-N-Perf, all you need is surfnperf.getMark('foo')';, and that's just the start!

Check out the JavaScript API to see all of its features and the full documentation for a list of methods & how to use them.

Available as an NPM Module, Ruby Gem, and a Bower package.

Usage

Including the code in your project

There are 2 pieces of code that need to be included in your webpage:

1. The following code must be included as high up in the source code of your base HTML document as possible, ideally right after the opening <head> tag:

<script>
  var SURF_N_PERF = {
    marks: {},
    highResMarks: {}
  };

  SURF_N_PERF.marks.pageStart = (new Date()).getTime();

  if(window.performance) {
    if(window.performance.now) {
      SURF_N_PERF.highResMarks.pageStart = window.performance.now();
    }
    if(window.performance.mark) {
      window.performance.mark('pageStart');
    }
  }

  SURF_N_PERF.visibility = {
    initialState: document.visibilityState,
    stateUpdates: [],
    hiddenProperty: null,
    stateProperty: null,
    eventName: null,
    markChange: function() {
      var markName = 'visibility' + SURF_N_PERF.visibility.stateUpdates.length;

      if (window.performance) {
        if (window.performance.mark) {
          window.performance.mark(markName);
        }

        if (window.performance.now) {
          SURF_N_PERF.highResMarks[markName] = window.performance.now();
        }
      }

      SURF_N_PERF.marks[markName] = new Date().getTime();

      SURF_N_PERF.visibility.stateUpdates.push(document[SURF_N_PERF.visibility.stateProperty]);
    },
  };

  if('hidden' in document) {
    SURF_N_PERF.visibility.hiddenProperty = 'hidden';
    SURF_N_PERF.visibility.stateProperty = 'visibilityState';
    SURF_N_PERF.visibility.eventName = 'visibilitychange';
  } else if('webkitHidden' in document) {
    SURF_N_PERF.visibility.hiddenProperty = 'webkitHidden';
    SURF_N_PERF.visibility.stateProperty = 'webkitVisibilityState';
    SURF_N_PERF.visibility.eventName = 'webkitvisibilitychange';
    SURF_N_PERF.visibility.initialState = document[SURF_N_PERF.visibility.stateProperty];
  }

  SURF_N_PERF.setPageLoad = function() {
    SURF_N_PERF.marks.loadEventEnd = (new Date()).getTime();

    if(window.performance && window.performance.now) {
      SURF_N_PERF.highResMarks.loadEventEnd = window.performance.now();
    }
  };

  SURF_N_PERF.setFirstPaint = function() {
    SURF_N_PERF.marks.firstPaintFrame = (new Date()).getTime();

    if(window.performance && window.performance.now) {
      SURF_N_PERF.highResMarks.firstPaintFrame = window.performance.now();

      if(window.performance.mark) {
        window.performance.mark('firstPaintFrame');
      }
    }
  };

  if(window.addEventListener) {
    if (SURF_N_PERF.visibility.stateProperty) {
      document.addEventListener(SURF_N_PERF.visibility.eventName, SURF_N_PERF.visibility.markChange, false);
    }
    window.addEventListener('load', SURF_N_PERF.setPageLoad, false);
  } else {
    window.attachEvent('onload', SURF_N_PERF.setPageLoad);
  }
  if (window.requestAnimationFrame) {
    window.requestAnimationFrame(SURF_N_PERF.setFirstPaint);
  }
</script>

That provides support for the following:

A "pageStart" mark for browsers that do not support Navigation Timing which can be used to compute durations from when the page first started loading (specifically, this mark falls between the domLoading and domInteractive attributes of Navigation Timing)
"pageStart" marks for browsers that support High Resolution Time and/or User Timing so that "pageStart" can be used as a consistent starting point for duration calculations across all browsers regardless of their supported features
A "loadEventEnd" mark for browsers that do not support Navigation Timing which can be used to compute durations from when the load event of the document is completed (loadEventEnd)
A "loadEventEnd" DOMHighResTimeStamp mark for calculating high resolution durations between a Navigation Timing mark and a user mark in browsers that support High Resolution Time but don't support User Timing
A "firstPaintFrame" mark (available in the best possible format for the browser, either a User Timing Mark, DOMHighResTimeStamp, or DOMTimeStamp) that approximates the Time To First Paint in browsers that support window.requestAnimationFrame.
The initial visibilityState as well as listeners for the "visibilitychange" event, enabling the ability to calculate how much time the page was hidden when you call surfnperf.getHiddenTime(). This is of particular importance as Chrome as of version 57 and Firefox as of version 57 limit the resources assigned to background (hidden) tabs.

2. Then just drop the surfnperf.min.js in your codebase and reference that JavaScript file in your HTML document. If you're using RequireJS or Browserify, it registers itself as 'surfnperf'.

3. (Optional) If you would like access to the Resource Timing helper functions, include resource-timing.js in your codebase and reference that JavaScript file in your HTML document. If you're using RequireJS, it registers itself as 'surfnperf/resource-timing', otherwise it is available on window as window.surfnperfRT.

Storing & Retrieving Performance Data

Details in the JavaScript API page in the wiki

Resource Timing Helper Functions

Documented in the JSDoc-generated Documentation

Ruby Project Integration

Using within a Rails project

The surfnperf Ruby Gem allows you to quickly & easily integrate Surf-N-Perf into your Rails projects. To include the necessary files, add surfnperf to your Gemfile:

gem 'surfnperf'

After a $ bundle install, you'll be able to include the main JavaScript file in your JavaScript manifest by simply adding:

//= require surfnperf

The necessary script for the <head> of your HTML document is also available to you via a partial template that you can include in the appropriate layout file for your page, such as app/views/layouts/application.html.erb by simply adding this line:

<%= render "surfnperf/head" %>

Those 3 lines of code are all your need to get started using Surf-N-Perf in Rails!

Using within a Middleman project

The surfnperf Ruby Gem also allows you to quickly & easily integrate Surf-N-Perf into your Middleman projects. Instructions are similar to the Rails instructions above, with one extra step. Start by adding at least v1.1.0 of surfnperf to your Middleman project's Gemfile:

gem "surfnperf", ">=1.1.0"

After a $ bundle install, you'll be able to include the main JavaScript file in your JavaScript manifest by simply adding:

//= require surfnperf

The necessary script for the <head> of your HTML document is also available to you via a custom defined helper that you can include in the appropriate layout file for your page, such as source/layouts/layout.erb by adding this line:

<%= surfnperf_head %>

You will also have to configure the extension for that helper to be recognized by Middleman by adding this line to your config.rb:

activate :surfnperf

You'll want to do that outside of your build-specific configuration (i.e. outside the configure :build do block) so that it is available when you run $ bundle exec middleman server

Those 4 lines of code are all your need to get started using Surf-N-Perf in Middleman!

Using within other Ruby projects that integrate with Sprockets

Sprockets is what powers the Asset Pipeline in Rails, Middleman, and other Ruby website tools. For these other Ruby projects that use Sprockets, integration is similar to the Rails instructions above, with one extra step:

Add surfnperf to your Gemfile:

gem 'surfnperf'

After a $ bundle install, include surfnperf.js in your JavaScript manifest by adding:

//= require surfnperf

For now, you'll have to manually include the necessary script for the <head> of your HTML document.

Running Tests & Other Development Tools

Tests are written in Jasmine and run with Karma

Install the dependencies by executing this command from the root of your Surf-N-Perf project directory:

$ npm install

If Grunt CLI has not been already installed, go install it.

And then run the tests, JSHint, beautify your code & generate the minified file with:

$ grunt dev

By default, it will run the tests using PhantomJS. You can also run the tests in any browser by going to http://localhost:9876/

The grunt dev process will watch for file updates, so as you modify surfnperf.js or the test files, it will automatically run jshint, jsbeautifier, uglify & the tests. To stop the watch process, press control + C

License

Licensed under the MIT License

Surf-N-Perf

Index

Surf-N-Perf

Usage

Including the code in your project

Storing & Retrieving Performance Data

Resource Timing Helper Functions

Ruby Project Integration

Using within a Rails project

Using within a Middleman project

Using within other Ruby projects that integrate with Sprockets

Running Tests & Other Development Tools

License