Roundtrip plugin API

The roundtrip plugin measures page load time, or other timers associated with the page. Its API is encapsulated within the BOOMR.plugins.RT namespace.

Configuration

All roundtrip plugin configuration items are under the RT namespace. The full configuration object is described in Howto #6 — Configuring boomerang.

cookie

[optional] The name of the cookie in which to store the start time for measuring page load time. The default name is RT. Set this to a falsy value like null or the empty string to ignore cookies and depend completely on the WebTiming API for the start time.

cookie_exp

[optional] The lifetime in seconds of the roundtrip cookie. This only needs to live for as long as it takes for a single page to load. Something like 10 seconds or so should be good for most cases, but to be safe, and to cover people with really slow connections, or users that are geographically far away from you, keep it to a few minutes. The default is set to 10 minutes.

strict_referrer

[optional] By default, boomerang will not measure a page's roundtrip time if the URL in the RT cookie doesn't match the current page's document.referrer. This is so because it generally means that the user visited a third page while their RT cookie was still valid, and this could render the page load time invalid.
There may be cases, though, when this is a valid flow — for example, you have an SSL page in between and the referrer isn't passed through. In this case, you'll want to set strict_referrer to false

Methods

init(oConfig)

Called by the BOOMR.init() method to configure the roundtrip plugin.

Parameters

oConfig

The configuration object passed in via BOOMR.init(). See the Configuration section for details.

Returns

a reference to the BOOMR.plugins.RT object, so you can chain methods.

startTimer(sName, [nValue])

Starts the timer named sName. Timers count in milliseconds. You must call endTimer() when this timer has complete for the measurement to be recorded in boomerang's beacon.

If passed in, the optional second parameter nValue is the timestamp in milliseconds to set the timer's start time to. This is useful if you need to record a timer that started before boomerang was loaded up.

Parameters:

sName

The name of the timer to start

nValue

[optional] A javascript timestamp value (milliseconds since the epoch). If set, the timer's start time will be set explicitly to this value. If not set, the current timestamp is used. You'd use this parameter if you measured a timestamp before boomerang was loaded and now need to pass that value to the roundtrip plugin.

Example:

See Howto #4 for an example that uses startTimer and endTimer.

Returns

a reference to the BOOMR.plugins.RT object, so you can chain methods.

Note

Calling startTimer("t_page") has the side-effect of calling endTimer("t_resp"). These timers are generally used to measure the time from (as close to) the first byte loaded to onload (t_page) and from onbeforeunload to the first byte time (t_resp). You do not need to explicitly call startTimer("t_resp").

endTimer(sName, [nValue])

Stops the timer named sName. It is not necessary for the timer to have been started before you call endTimer(). If a timer with this name was not started, then the unload time of the previous page is used instead. This allows you to measure the time across pages.

Parameters:

sName

The name of the timer to stop

nValue

[optional] A javascript timestamp value (milliseconds since the epoch). If set, the timer's stop time will be set explicitly to this value. If not set, the current timestamp is used. You'd use this parameter if you measured a timestamp before boomerang was loaded and now need to pass that value to the roundtrip plugin.

Example:

See Howto #4 for an example that uses startTimer and endTimer.

Returns

a reference to the BOOMR.plugins.RT object, so you can chain methods.

setTimer(sName, nValue)

Sets the timer named sName to an explicit time measurement. You'd use this method if you measured time values within your page before boomerang was loaded and now need to pass those values to the roundtrip plugin for inclusion in the beacon. It is not necessary to call startTimer() or endTimer() before calling setTimer(). If you do, the old values will be ignored and the value passed in to this function will be used.

Parameters:

sName

The name of the timer to set

nValue

The value in milliseconds to set this timer to.

Returns

a reference to the BOOMR.plugins.RT object, so you can chain methods.

done()

Typically called automatically when boomerang's page_ready event fires, but it may also be called explicitly to measure the load time of transitions that do not involve a onload event.

This method calculates page load time, and determines whether the values we have are good enough to be beaconed. It then signals the BOOMR object via its sendBeacon method.

Example:

See Howto #2 for an example of explicitly calling the done() method.

Returns

a reference to the BOOMR.plugins.RT object, so you can chain methods.

See also

• Roundtrip methodology for details on how roundtrip time is measured.

is_complete()

Called by BOOMR.sendBeacon() to determine if the roundtrip plugin has finished what it's doing or not.

Returns

• true if the plugin has completed.
• false if the plugin has not completed.

Beacon Parameters

This plugin adds the following parameters to the beacon:

t_done

[optional] Perceived load time of the page.

t_page

[optional] Time taken from the head of the page to page_ready.

t_resp

[optional] Time taken from the user initiating the request to the first byte of the response.

t_other

[optional] Comma separated list of additional timers set by page developer. Each timer is of the format name|value

t_load

[optional] If the page were prerendered, this is the time to fetch and prerender the page.

t_prerender

[optional] If the page were prerendered, this is the time from start of prefetch to the actual page display. It may only be useful for debugging.

t_postrender

[optional] If the page were prerendered, this is the time from prerender finish to actual page display. It may only be useful for debugging.

r

URL of page that set the start time of the beacon.

r2

[optional] URL of referrer of current page. Only set if different from r and strict_referrer has been explicitly turned off.

nu

[optional] URL of next page if the user clicked a link or submitted a form

rt.start

Specifies where the start time came from. May be one of cookie for the start cookie, navigation for the W3C navigation timing API, csi for older versions of Chrome or gtb for the Google Toolbar.

rt.tstart

The start time timestamp.

rt.cstart

[optional] The start time stored in the cookie if different from rt.tstart

rt.bstart

The timestamp when boomerang started executing

rt.end

The timestamp when the t_done timer ended (rt.end - rt.tstart === t_done)

rt.bmr.{...}

[optional] Several parameters that include resource timing information for boomerang itself, ie, how long did boomerang take to load

rt.subres

[optional] Set to 1 if this beacon is for a sub-resource of a primary page beacon. This is typically set by XHR beacons, and you will need to use a separate identifier to tie the primary beacon and the subresource beacon together on the server-side.

rt.quit

[optional] This parameter will exist (but have no value) if the beacon was fired as part of the onbeforeunload event. This is typically used to find out how much time the user spent on the page before leaving, and is not guaranteed to fire.

rt.abld

[optional] This parameter will exist (but have no value) if the onbeforeunload event fires before the onload event fires. This can happen, for example, if the user left the page before it completed loading.

rt.ntvu

[optional] This parameter will exist (but have no value) if the onbeforeunload event fires before the page ever became visible. This can happen if the user opened the page in a background tab, and closed it without viewing it, and also if the page was pre-rendered, but never made visible. Use this to check your pre-render success ratio.

The latest code and docs is available on github.com/SOASTA/boomerang