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 both an NPM Module and a Ruby Gem.
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.setPageLoad = function() {
SURF_N_PERF.marks.loadEventEnd = (new Date()).getTime();
if(window.performance && window.performance.now) {
SURF_N_PERF.highResMarks.loadEventEnd = window.performance.now();
}
};
if(window.addEventListener) {
window.addEventListener('load', SURF_N_PERF.setPageLoad, false);
} else {
window.attachEvent('onload', SURF_N_PERF.setPageLoad);
}
</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
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'.
Details in the JavaScript API page in the wiki
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!
Sprockets is what powers the Asset Pipeline in Rails, as well as other Ruby website tools such as Middleman. 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. If someone would like to update the Ruby Gem to work as a proper Middleman Extension, we'd happily accept a pull request.
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
Licensed under the MIT License