mPulse Boomerang Class: 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
servertiming: Compressed ServerTiming data
restiming.ct: contentType map
restiming.dt: deliveryType map
restiming.nhp: nextHopProtocol map

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 (and additional details):

{ "[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]*[special1]*[special2]"

initiatorType is a simple map from the PerformanceResourceTiming initiatorType (which is a string) to an integer, according to the BOOMR.plugins.ResourceTiming.INITIATOR_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)

Additional special data may be appended to the end of the timings data, depending on browser support and whether it was same- or cross-origin.

See https://github.com/nicjansma/resourcetiming-compression.js for more details on each special data type.

See:

http://www.w3.org/TR/resource-timing/

Members

INITIATOR_TYPES :string

Initiator type mapping.

If no match, the initiatorType 'other' will be chosen

Type:

string

Properties:

Name	Type	Default	Description
`other`	string	0	Unknown type
`img`	string	1	IMG element (or IMAGE element inside a SVG for IE, Edge and Firefox)
`link`	string	2	LINK element (i.e. CSS)
`script`	string	3	SCRIPT element
`css`	string	4	Resource referenced in CSS
`xmlhttprequest`	string	5	XMLHttpRequest
`html`	string	6	The root HTML page itself
`image`	string	7	IMAGE element inside a SVG
`beacon`	string	8	sendBeacon
`fetch`	string	9	Fetch API
`iframe`	string	a	An IFRAME
`subdocument`	string	a	IE11 and Edge (some versions) send "subdocument" instead of "iframe"
`body`	string	b	BODY element
`input`	string	c	INPUT element
`frame`	string	a	FRAME element
`object`	string	d	OBJECT element
`video`	string	e	VIDEO element
`audio`	string	f	AUDIO element
`source`	string	g	SOURCE element
`track`	string	h	TRACK element
`embed`	string	i	EMBED element
`eventsource`	string	j	EventSource
`navigation`	string	6	The root HTML page itself
`"early-hints"`	string	k	Early Hints
`ping`	string	l	HTML ping Attribute
`font`	string	m	CSS font at-rule

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
`prefetch`	number	1
`preload`	number	2
`prerender`	number	3
`stylesheet`	number	4

RT_FIELDS_TIMESTAMPS

ResourceTiming timestamp fields, in order.

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 `PerformanceResourceTiming`s
`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	Default	Description
`ResourceTiming.xssBreakWords`	Array.<string>	<optional>	["href", "src", "action"]	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>	false	Whether or not to clear ResourceTiming data on each beacon.
`ResourceTiming.urlLimit`	number	<optional>	500	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.trackedResourceTypes`	Array.<string> \| string	<optional>	*	Array of resource types to track, or '*' for all.
`ResourceTiming.serverTiming`	boolean	<optional>	true	Whether or not to gather ServerTiming.
`ResourceTiming.monitorClearResourceTimings`	boolean	<optional>	false	Whether or not to instrument `performance.clearResourceTimings`.
`ResourceTiming.splitAtPath`	boolean	<optional>	false	Whether or not to split the ResourceTiming compressed Trie at the path separator (faster processing, but larger result).
`ResourceTiming.getSrcsetDimensions`	boolean	<optional>	false	Whether or not to collect physical dimensions of srcset images. Setting this will cause un-cacheable images to be re-downloaded.
`ResourceTiming.jsUrl`	boolean	<optional>	false	Whether or not to encode as JSURL

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.

Beacon Parameters

See:

Members

INITIATOR_TYPES :string

Type:

Properties:

REL_TYPES :number

Type:

Properties:

RT_FIELDS_TIMESTAMPS

Methods

addResources(resources, epoch)

Parameters:

addResourceTimingToBeacon(from, to)

Parameters:

calculateResourceTimingUnion(resources)

Parameters:

Returns:

getCompressedResourceTiming(from, to)

Parameters:

Returns:

getFilteredResourceTiming(from, to, initiatorTypes)

Parameters:

Returns:

init(config)

Parameters:

Properties

Returns:

is_complete()

Returns:

is_enabled()

Returns:

is_supported()

Returns:

Search results