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

"early-hints" number k

Early Hints

ping number l

HTML ping Attribute

font number 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 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.