Resource Timing plugin API

The Resource Timing plugin collects metrics from modern user agents that support the W3C Resource Timing specification. The Resource Timing API is encapsulated within the BOOMR.plugins.ResourceTiming namespace.

Note that the Resource Timing plugin isn't included by default in boomerang.js. See Howto #9 for details on how to include the plugin in your boomerang deployment.

Methods

init()

Called by BOOMR.init() to configure the Resource Timing plugin. The Resource Timing plugin doesn't require any configuration parameters, since it simply reads values from the browser's window.performance object (if available) and adds them to the beacon request data.

Returns

a reference to the BOOMR.plugins.ResourceTiming object.

Note

If the executing user agent doesn't implement the Resource Timing specification, the plugin won't add any data to the beacon.

is_complete()

Called by BOOMR.sendBeacon() to determine if the Resource Timing plugin has finished.

Returns

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

Beacon Parameters

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 following table:

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":

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

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