OSS Boomerang

BOOMR.plugins. ResourceTiming

Plugin to collect metrics from the W3C ResourceTiming API.

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

Beacon Parameters

This plugin adds the following parameters to the beacon for Page Loads:

  • restiming: Compressed ResourceTiming data

The ResourceTiming plugin adds an object named restiming to the beacon data.

restiming is an optimized Trie structure, where the keys are the ResourceTiming URLs, and the values correspond to those URLs' PerformanceResourceTiming timestamps:

{ "[url]": "[data]"}

The Trie structure is used to minimize the data transmitted from the ResourceTimings.

Keys in the Trie are the ResourceTiming URLs. For example, with a root page and three resources:

  • http://abc.com/
  • http://abc.com/js/foo.js
  • http://abc.com/css/foo.css
  • http://abc.com/css/foo.png (downloaded twice)

Then the Trie might look like this:

// Example 1
{
  "http://abc.com/":
  {
    "|": "0,2",
    "js/foo.js": "3a,1",
    "css/": {
      "foo.css": "2b,2",
      "foo.png": "1c,3|1d,a"
    }
  }
}

If a resource's URL is a prefix of another resource, then it terminates with a pipe symbol (|). In Example 1, http://abc.com (the root page) is a prefix of http://abc.com/js/foo.js, so it is listed as http://abc.com| in the Trie.

If there is more than one ResourceTiming entry for a URL, each entry is separated by a pipe symbol (|) in the data. In Example 1 above, foo.png has been downloaded twice, so it is listed with two separate page loads, 1c,3 and 1d,a.

The value of each key is a string, which contains the following components:

data = "[initiatorType][timings]"

initiatorType is a simple map from the PerformanceResourceTiming initiatorType (which is a string) to an integer, according to the BOOMR.plugins.ResourceTiming.INITAITOR_TYPES enum.

timings is a string of Base-36 encoded timestamps from the PerformanceResourceTiming interface. The values in the string are separated by commas:

timings = "[startTime],[responseEnd],[responseStart],[requestStart],[connectEnd],[secureConnectionStart],[connectStart],[domainLookupEnd],[domainLookupStart],[redirectEnd],[redirectStart]"

startTime is a DOMHighResTimeStamp from when the resource started (Base 36).

All other timestamps are offsets (rounded to milliseconds) from startTime (Base 36). For example, responseEnd is calculated as:

responseEnd: base36(round(responseEnd - startTime))

If the resulting timestamp is 0, it is replaced with an empty string ("").

All trailing commas are removed from the final string. This compresses the timing string from timestamps that are often 0. For example, here is what a fully-redirected resource might look like:

{ "http://abc.com/this-resource-was-redirected": "01,1,1,1,1,1,1,1,1,1,1" }

While a resource that was loaded from the cache (and thus only has startTime and responseEnd timestamps) might look like this:

{ "http://abc.com/this-resource-was-redirected": "01,1" }

Note that some of the metrics are restricted and will not be provided cross-origin unless the Timing-Allow-Origin header permits.

Putting this all together, let's look at http://abc.com/css/foo.png in Example 1. We find it was downloaded twice "1c,3|1d,a":

  • 1c,3:
    • 1: initiatorType = 1 (IMG)
    • c: startTime = c (12ms)
    • 3: responseEnd = 3 (3ms from startTime, or at 15ms)
  • 1d,a:
    • 1: initiatorType = 1 (IMG)
    • d: startTime = d (13ms)
    • a: responseEnd = a (10ms from startTime, or at 23ms)

See:

Members

INITIATOR_TYPES :number

Type:

  • number

Properties:

Name Type Default Description
other number 0

Unknown type
img number 1

IMG element (or IMAGE element inside a SVG for IE, Edge and Firefox)
link number 2

LINK element (i.e. CSS)
script number 3

SCRIPT element
css number 4

Resource referenced in CSS
xmlhttprequest number 5

XMLHttpRequest
html number 6

The root HTML page itself
image number 7

IMAGE element inside a SVG
beacon number 8

sendBeacon
fetch number 9

Fetch API
iframe number a

An IFRAME
subdocument number a

IE11 and Edge (some versions) send "subdocument" instead of "iframe"
body number b

BODY element
input number c

INPUT element
frame number a

FRAME element
object number d

OBJECT element
video number e

VIDEO element
audio number f

AUDIO element
source number g

SOURCE element
track number h

TRACK element
embed number i

EMBED element
eventsource number j

EventSource
navigation number 6

The root HTML page itself

REL_TYPES :number

These are the only rel types that might be reference-able from ResourceTiming.

https://html.spec.whatwg.org/multipage/links.html#linkTypes

Type:

  • number

Properties:

Name Type Default Description
prefetch number 1
preload number 2
prerender number 3
stylesheet number 4

Methods

addResources(resources, epoch)

Saves an array of PerformanceResourceTiming-shaped objects which we will later insert into the trie.

Parameters:

Name Type Description
resources array.<object>

Array of objects that are shaped like PerformanceResourceTimings
epoch high-resolution-timestamp

Optional epoch for all of the timestamps of all of the resources

addResourceTimingToBeacon(from, to)

Adds 'restiming' and 'servertiming' to the beacon

Parameters:

Name Type Description
from number

Only get timings from
to number

Only get timings up to

calculateResourceTimingUnion(resources)

Calculates the union of durations of the specified resources. If any resources overlap, those timeslices are not double-counted.

Parameters:

Name Type Description
resources Array.<ResourceTiming>

Resources

Returns:

Duration, in milliseconds

getCompressedResourceTiming(from, to)

Gathers performance entries and compresses the result.

Parameters:

Name Type Description
from number

Only get timings from
to number

Only get timings up to

Returns:

Type: object

An object containing the Optimized performance entries trie and the optimized server timing lookup

getFilteredResourceTiming(from, to, initiatorTypes)

Gathers a filtered list of performance entries.

Parameters:

Name Type Description
from number

Only get timings from
to number

Only get timings up to
initiatorTypes Array.<string>

Array of initiator types

Returns:

Type: Array.<ResourceTiming>

Matching ResourceTiming entries

init(config)

Initializes the plugin.

Parameters:

Name Type Description
config object

Configuration

Properties
Name Type Argument Description
ResourceTiming.xssBreakWorks Array.<string> <optional>

Words that will be broken (by ensuring the optimized trie doesn't contain the whole string) in URLs, to ensure NoScript doesn't think this is an XSS attack.

Defaults to DEFAULT_XSS_BREAK_WORDS.
ResourceTiming.clearOnBeacon boolean <optional>

Whether or not to clear ResourceTiming data on each beacon.
ResourceTiming.urlLimit number <optional>

URL length limit, after which ... will be used
ResourceTiming.trimUrls Array.<string> | Array.<RegExp> <optional>

List of strings of RegExps to trim from URLs.
ResourceTiming.monitorClearResourceTimings boolean <optional>

Whether or not to instrument performance.clearResourceTimings.
ResourceTiming.splitAtPath boolean <optional>

Whether or not to split the ResourceTiming compressed Trie at the path separator (faster processing, but larger result).
ResourceTiming.getSrcsetDimensions boolean <optional>

Whether or not to collect physical dimensions of srcset images. Setting this will cause uncacheable images to be re-downloaded.

Returns:

BOOMR.plugins.ResourceTiming The ResourceTiming plugin for chaining

is_complete()

Whether or not this plugin is complete

Returns:

Type: boolean

true if the plugin is complete

is_enabled()

Whether or not this ResourceTiming is enabled and supported.

Returns:

Type: boolean

true if ResourceTiming plugin is enabled.

is_supported()

Whether or not ResourceTiming is supported in this browser.

Returns:

Type: boolean

true if ResourceTiming is supported.