OSS Boomerang

Building

Boomerang is split into the main framework (boomerang.js) and plugins (plugins/*.js).

boomerang.js on its own will not do anything interesting. To enable performance measurements of your site, you will want to include several plugins.

Choosing Plugins

Each plugin lives on its own in the plugins/ directory. Plugins are split into core measurement components, though some depend on each other.

The default set of plugins for a "full" build of Boomerang can be seen in plugins.json in the root directory. You can modify this file to choose which plugins you want for measurement.

You can read about each plugin in its documentation. Here is a basic description of each plugin:

There are also a few utility plugins:

To monitor basic page load performance for a traditional website, we would recommend:

To monitor a Single Page App website, we would additionally recommend the following:

See the build flavors section below for suggested ways of building Boomerang.

Including Boomerang on your site.

boomerang can be included on your page in one of two ways: synchronously or asynchronously.

The asynchronous method is recommended.

After the core JavaScript files are loaded, you will need to call BOOMR.init to initialize Boomerang and all of its plugins. See each plugin's documentation for the available configuration options.

The simple synchronous way

Simply include boomerang.js and any desired plugins as a <script> tag.

<script src="boomerang.js"></script>
<script src="plugins/rt.js"></script>
<!-- any other plugins you want to include -->
<script>
  BOOMR.init({
    beacon_url: "http://yoursite.com/beacon/"
  });
</script>

Each plugin has its own configuration as well -- these configuration options should be included in the BOOMR.init() call:

BOOMR.init({
  beacon_url: "http://yoursite.com/beacon/",
  ResourceTiming: {
    enabled: true,
    clearOnBeacon: true
  }
});

The faster, more involved, asynchronous way

Loading boomerang asynchronously ensures that even if boomerang.js is unavailable (or loads slowly), your host page will not be affected.

1. Add a plugin to init your code

Create a plugin (or use the sample zzz-last-plugin.js) with a call to BOOMR.init:

BOOMR.init({
  config: parameters,
  ...
});
BOOMR.t_end = new Date().getTime();

You could also include any other code you need. For example, you could include a timer to measure when boomerang has finished loading (as above).

2. Build boomerang

The build process bundles boomerang.js and all of the plugins listed in plugins.json (in that order).

If you want to have a custom set of plugins, you can create a plugins.user.json and that file will be used instead (this file is excluded from this repository's Git).

To build boomerang with all of your desired plugins, you would run:

grunt clean build

This creates a deployable boomerang in the build directory, e.g. build/boomerang-<version>.min.js.

Install this file on your web server or origin server where your CDN can pick it up. Set a far future max-age header for it. This file will never change.

The Build Process

Build requires NodeJS to execute Grunt.js to build Boomerang.

To install Grunt globally:

npm install -g grunt-cli

You can get a full build of boomerang by running the following:

grunt clean build

The main build targets are:

  • clean cleans the build/ directory
  • build builds a new version of Boomerang from scratch
  • lint runs lint on the project
  • test runs Tests

A full list of build targets are avaialble in Gruntfile.js.

Grunt build options:

  • --build-number Specifies the minor build number
  • --build-revision Specifies the revision build number

Build Numbers

Boomerang follows SemVer:

major.minor.revision

For each build of Boomerang, the major build version is specified in package.json as releaseVersion.

The minor version defaults to 0. Each build can then specify its --build-number to change the minor version.

The revision defaults to 0. Each build can then specify its --build-revision to change the revision.

Build Flavors

By default Boomerang will bundle all plugins defined in plugins.json (under the top-level "plugins": [] key) into the build.

It is recommended that you tune your build to include just the plugins/features you need, so you can reduce the size and complexity of the Boomerang build.

Some guidance on choosing plugins is above, but Boomerang also defines a few "flavors" of builds that bundle common plugins together.

These flavors are also defined in plugins.json under the "flavors": {} key.

For example, here's a definition of the "minimal" build we recommend:

"minimal": {
    "comment": "Minimal recommended plugins",
    "revision": 10,
    "plugins": [
        "plugins/rt.js",
        "plugins/navtiming.js"
    ]
},

For each flavor, the "plugins": [] key lists which plugins apply to that flavor.

To build Boomerang with a specific flavor, you can add a --build-flavor= argument to grunt:

grunt clean build --build-flavor=minimal --build-number=1000

The resulting output file will be set to the specified Revision in the "revision" field above, e.g. 1.1000.10 for the minimal flavor.

You can also create a plugins.user.json file and that will be used instead of plugins.json (this file is excluded from this repository's Git).