OSS Boomerang

BOOMR.plugins. RT

The roundtrip (RT) plugin measures page load time, or other timers associated with the page.

For information on how to include this plugin, see the Building tutorial.

Beacon Parameters

This plugin adds the following parameters to the beacon:

  • t_done: Perceived load time of the page.
  • t_page: Time taken from the head of the page to BOOMR#event:page_ready.
  • t_page.inv: If there was a problem detected with the start/end times of t_page. This can happen due to bugs in NavigationTiming clients, where responseEnd happens after all other NavigationTiming events.
  • t_resp: Time taken from the user initiating the request to the first byte of the response.
  • t_other: Comma separated list of additional timers set by page developer. Each timer is of the format name|value
  • t_load: If the page were prerendered, this is the time to fetch and prerender the page.
  • t_prerender: 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: If the page were prerendered, this is the time from prerender finish to actual page display. It may only be useful for debugging.
  • vis.pre: 1 if the page transitioned from prerender to visible
  • r: URL of page that set the start time of the beacon.
  • nu: 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 NavigationTiming API,
    • csi for older versions of Chrome or gtb for the Google Toolbar.
    • manual for XHR beacons
    • none if the start could not be detected
  • rt.tstart: The start time timestamp.
  • rt.nstart: The navigationStart timestamp, if different from rt.tstart. This could happen for XHR beacons, where rt.tstartis the start of the XHR fetch, andnt_nav_st won't be on the beacon. It could also happen for SPA Soft beacons, wherert.tstart` is the start of the Soft Navigation.
  • rt.cstart: The start time stored in the cookie if different from rt.tstart.
  • rt.bstart: The timestamp when boomerang started executing.
  • rt.blstart: The timestamp when the boomerang was added to the host page.
  • rt.end: The timestamp when the t_done timer ended (rt.end - rt.tstart === t_done)
  • rt.bmr: Several parameters that include resource timing information for boomerang itself, ie, how long did boomerang take to load
  • rt.subres: 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: 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: 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: 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.
  • http.method: For XHR beacons, the HTTP method if not GET.
  • http.errno: For XHR beacons, the HTTP result code if not 200.
  • http.hdr: For XHR beacons, headers if available.
  • http.type: For XHR beacons, value of f for fetch API requests. Not set for XHRs.
  • xhr.sync: For XHR beacons, 1 if it was sent synchronously.
  • http.initiator: The initiator of the beacon:
    • (empty/missing) for the page load beacon
    • xhr for XHR beacons
    • spa for SPA Soft Navigations
    • spa_hard for SPA Hard Navigations
  • fetch.bnu: For XHR beacons from fetch API requests, 1 if fetch response body was not used.
  • rt.tt: Sum of load times across session
  • rt.obo: Number of pages in session that did not have a load time
  • xhr.ru: final response URL after any redirects
    • XMLHttpRequest: it will be present if any redirects happened and final URL is not equivalent to the final response URL after any redirects.
    • fetch: it will only be present if any redirects happened

Cookie

The session information is stored within a cookie.

You can customise the name of the cookie where the session information will be stored via the RT.cookie option.

By default this is set to RT.

This cookie is set to expire in 7 days. You can change its lifetime using the RT.cookie_exp option.

During that time, you can also read the value of the cookie on the server side. Its format is as follows:

RT="ss=nnnnnnn&si=abc-123...";

The parameters are defined as:

  • ss [string] [timestamp] Session Start (Base36)
  • si [string] [guid] Session ID
  • sl [string] [count] Session Length (Base36)
  • tt [string] [ms] Sum of Load Times across the session (Base36)
  • obo [string] [count] Number of pages in the session that had no load time (Base36)
  • dm [string] [domain] Cookie domain
  • bcn [string] [URL] Beacon URL
  • rl [number] [boolean] Whether or not the session is Rate Limited
  • se [string] [s] Session expiry (Base36)
  • ld [string] [timestamp] Last load time (Base36, offset by ss)
  • ul [string] [timestamp] Last beforeunload time (Base36, offset by ss)
  • hd [string] [timestamp] Last unload time (Base36, offset by ss)
  • cl [string] [timestamp] Last click time (Base36, offset by ss)
  • r [string] [URL] Referrer URL (hashed, only if NavigationTiming isn't
  • supported and if strict_referrer is enabled)
  • nu [string] [URL] Clicked URL (hashed)
  • z [number] [flags] Compression flags

Methods

addTimersToBeacon(vars, source)

Adds all known timers to the beacon

Parameters:

Name Type Description
vars object

(unused)
source string

Source

clearTimer(timer_name)

Clears (removes) the specified timer

Parameters:

Name Type Description
timer_name string

Timer name

done(edata, ename)

Called when the page has reached a "usable" state. This may be when the onload event fires, or it could be at some other moment during/after page load when the page is usable by the user

Parameters:

Name Type Description
edata object

Event data
ename string

Event name

Returns:

BOOMR.plugins.RT The RT plugin for chaining

endTimer(timer_name [, time_value])

Stops the timer named timer_name.

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:

Name Type Argument Description
timer_name string

The name of the timer to start
time_value TimeStamp <optional>

If set, the timer's stop time will be set explicitly to this value. If not set, the current timestamp is used.

Returns:

BOOMR.plugins.RT The RT plugin for chaining

getCookie()

Gets RT cookie data from the cookie and returns it as an object.

Also decompresses the cookie if it has been compressed.

Returns:

Type: RTCookie | false

an object containing RT Cookie data or false if no cookie is available

init(config)

Initializes the plugin.

Parameters:

Name Type Description
config object

Configuration

Properties
Name Type Argument Description
RT.cookie string <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 to ignore cookies and depend completely on the NavigationTiming API for the start time.
RT.cookie_exp string <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.
RT.strict_referrer string <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 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.

The default is true.

Returns:

BOOMR.plugins.RT The RT plugin for chaining

is_complete()

Whether or not this plugin is complete

Returns:

Type: boolean

true if the plugin is complete

navigationStart()

Gets the Navigation Start time

Returns:

Type: TimeStamp

Navigation start

setTimer(timer_name, time_value)

Sets the timer named timer_name to an explicit time measurement time_value.

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 BOOMR.plugins.RT 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:

Name Type Description
timer_name string

The name of the timer to start
time_value number

The value in milliseconds to set this timer to.

Returns:

BOOMR.plugins.RT The RT plugin for chaining

startTimer(timer_name [, time_value])

Starts the timer named timer_name.

Timers count in milliseconds.

You must call BOOMR.plugins.RT.endTimer when this timer has completed for the measurement to be recorded in the beacon.

If passed in, the optional second parameter time_value 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.

Parameters:

Name Type Argument Description
timer_name string

The name of the timer to start
time_value TimeStamp <optional>

If set, the timer's start time will be set explicitly to this value. If not set, the current timestamp is used.

Returns:

BOOMR.plugins.RT The RT plugin for chaining

updateCookie()

Updates the RT cookie.