Everything in boomerang is accessed through the BOOMR object. Each plugin has its
own API, but is reachable through BOOMR.plugins. This document describes the main
BOOMR object.
To access any of the following, dereference the BOOMR object. eg: use BOOMR.version
to get the version string.
The version number of the boomerang library. This is a string, formatted as major.minor.patchlevel. Standard version numbering rules apply
The timestamp when the boomerang code showed up on the page.
The timestamp when the boomerang code finished loading. Note, this will only be set if you used make to make a combined version of boomerang.
An object containing all plugins that have been added to boomerang. If you build your own plugin, it should be added to this object:
BOOMR.plugins.MyPlugin = {
...
};
Configuring boomerang is described in Howto #6 — Configuring boomerang.
Parameters relevant to the BOOMR object are:
'GET', 'POST' or 'AUTO' (the default).
The AUTO setting will make a GET request unless the combined beacon URL plus query string
exceeds 2000 characters, in which case it will issue a POST. The data will be
application/x-www-form-urlencoded.
'Authorization', but may be explicitly set using this
setting. Some services use specialized authentication keys such as 'X-API-KEY'.
'SPLUNK 4F00X7AF-B3D3-4E07-8C6C-12345678901'. The value supplied here will be contatenated with the beacon_auth_key to
form a complete HTTP request header field such as 'Authorization':'SPLUNK 4F00X7AF-B3D3-4E07-8C6C-12345678901'.
foo.com format, it will probably get it
wrong. It's a good idea to set this to whatever part of your domain you'd like to
share bandwidth and performance measurements across.log
parameter to a function that logs messages.function log(oMessage, sLevel, sSource);Where:
log to null.
page_ready handler to
the window.onload event. If you set autorun to false,
this will not happen and you will need to call BOOMR.page_ready() yourself.
The init method that you to call to initialise boomerang. Call this method once after you've loaded the boomerang javascript. It accepts a single configuration object as a parameter. See the Configuration section for details.
a reference to the BOOMR object, so you can chain methods.
Method that fires the page_ready event. Call this only if you've set autorun to
false when calling the init() method. You should call this method when you determine that
your page is ready to be used by your user. This will be the end-time used in the page load time measurement.
See Howto #1b for an example of how to use this method.
a reference to the BOOMR object, so you can chain methods.
The subscribe method is used to subscribe an event handler to one of boomerang's events. It accepts four parameters:
function(oEventData, oCallbackData);
this
within the callback function will refer to oCallbackScope
The page_ready and page_unload events are most useful to plugins while the
before_beacon event is useful to code that wants to do something with the beacon parameters
before the beacon is fired. See the events section for more details.
a reference to the BOOMR object, so you can chain methods.
Add one or more parameters to the beacon. This method is used by plugins to add parameters to the beacon, but may also be used by the page developer to tag the current request.
See Howto #5 for an example of using addVar().
This method may either be called with a single object containing key/value pairs, or with two parameters, the first is the variable name and the second is its value. All names should be strings usable in a URL's query string. We recommend only using alphanumeric characters and underscores, but you can use anything you like. Values should be strings (or numbers), and have the same restrictions as names.
a reference to the BOOMR object, so you can chain methods.
Removes one or more variables from the beacon URL. This is useful within a plugin to reset the values of
parameters that it is about to set. It can also be used in a before_beacon handler to stop
the beacon from being sent. See Howto #5 for how to do this.
This method accepts either a list of variable names, or a single array containing a list of variable names.
a reference to the BOOMR object, so you can chain methods.
Request boomerang to send its beacon. Boomerang may ignore this request. When this method is called,
boomerang checks all plugins. If any plugin has not completed its checks (ie, the plugin's is_complete()
method returns false, then this method does nothing. If all plugins have completed, then this method fires the
before_beacon event with all variables that will be sent on the beacon.
After all before_beacon handlers return, this method checks if a beacon_url has been
configured and if there are any beacon parameters to be sent. If both are true, it fires the beacon.
a reference to the BOOMR object, so you can chain methods.
Log a sMessage to the configured logger with a level of sLevel. This method
simply passes all logging information on to the configured logger. See
Howto #6 for details on how to configure this.
You probably want to use one of the convenience methods below instead that set the log level correctly.
nothing
Log sMessage to the configured logger with a level of debug. If sSource is set,
it is appended to the string "boomerang." and set as the source of the log message. Use this
parameter to mention a plugin name and/or a line number/function name.
a reference to the BOOMR object, so you can chain methods.
Log sMessage to the configured logger with a level of info. If sSource is set,
it is appended to the string "boomerang." and set as the source of the log message. Use this
parameter to mention a plugin name and/or a line number/function name.
a reference to the BOOMR object, so you can chain methods.
Log sMessage to the configured logger with a level of warn. If sSource is set,
it is appended to the string "boomerang." and set as the source of the log message. Use this
parameter to mention a plugin name and/or a line number/function name.
a reference to the BOOMR object, so you can chain methods.
Log sMessage to the configured logger with a level of error. If sSource is set,
it is appended to the string "boomerang." and set as the source of the log message. Use this
parameter to mention a plugin name and/or a line number/function name.
a reference to the BOOMR object, so you can chain methods.
Fired when the page is usable by the user. By default this is fired when window.onload fires,
but if you set autorun to false when calling BOOMR.init(), then
you must explicitly fire this event by calling BOOMR.page_ready().
No additional event data is passed to the callback function. Any callback data is passed as specified in
the subscribe() method.
Fired just before the browser unloads the page. This is fired when window.onbeforeunload fires
(onunload on Opera).
No additional event data is passed to the callback function. Any callback data is passed as specified in
the subscribe() method.
Fired if the page's visibility state changes. Currently only supported on IE10 and Chrome.
No additional event data is passed to the callback function. Any callback data is passed as specified in
the subscribe() method.
Fired just before the beacon is sent to the server. You can stop the beacon from firing by calling
BOOMR.removeVar() for all beacon parameters.
The callback function is called with two parameters. The first parameter is an object containing all
parameters that will be added to the beacon. The second parameter is the callback data object that
was passed in to the subscribe() method. If the callback function removes all parameters
from boomerang, the beacon will not fire.
On its own, with no plugins set up, boomerang will send the following parameters across through the beacon:
Each plugin may add its own parameters, and these are specified in each plugin's API docs.
The latest code and docs is available on github.com/SOASTA/boomerang