Resource Timing API
The Resource Timing
interfaces enable retrieving and analyzing detailed network timing data regarding the loading of an application's resource(s). An application can use the timing metrics to determine, for example, the length of time it takes to load a specific resource, such as an XMLHttpRequest
, <SVG>
, image, or script.
The interface's properties create a resource loading timeline with high-resolution timestamps
for network events such as redirect start and end times, DNS lookup start and end times, request start, response start and end times, etc. The interface also includes other properties that provide data about the size of the fetched resource as well as the type of resource that initiated the fetch.
This document provides an overview of the Resource Timing
interfaces. For more details about the interfaces including examples, see the each interface's reference page, Using Resource Timing and the references in the See also section. For a graphical representation of the resource timing processing model, see the resource timing phases figure.
Note: the PerformanceResourceTiming
interface extends the PerformanceEntry
for performance entries
which have an entryType
of "resource
".
High-resolution time stamps
Several of the Resource Timing
properties return high-resolution timestamps. These timestamps have a
type, and as its name implies, they represent a high-resolution point in time. This type is a DOMHighResTimeStamp
double
, and its value is a discrete point in time or the difference in time between two discrete points in time.
The unit of DOMHighResTimeStamp
is milliseconds and should be accurate to 5 µs (microseconds). However, If the browser is unable to provide a time value accurate to 5 microseconds (because, for example, due to hardware or software constraints), the browser can represent a the value as a time in milliseconds accurate to a millisecond.
Resoure loading timestamps
An application can get timestamps for the various stages used to load a resource. The first property in the processing model is startTime
which returns the timestamp immediately before the resource loading process begins. The fetchStart
timestamps follows and redirect processing (if applicable) and preceeds DNS lookup. The next stages are connectStart
and connectEnd
which are the timestamps immediately before and after connecting to the server, respectively. The last three timestamps are, in order: requestStart
- the timestamp before the browser starts requesting the resource from the server; responseStart
- the timestamp after the browser receives the first byte of the response from the server; and responseEnd
- the timestamp after the browser receives the last byte of the resource. If the resource is loaded via a secure connection a secureConnectionStart
timestamp will be available between the connection start and end events.
The
interface also includes several network timing properties. The PerformanceResourceTiming
redirectStart
and redirectEnd
properties return timestamps
for redirect start and end times, respectively. Likewise, the The domainLookupStart
and domainLookupEnd
properties return timestamps
for DNS lookup start and end times, respectively.
Resource size
The PerformanceResourceTiming
interface has three properties that can be used to obtain size data about a resource. The transferSize
property returns the size (in octets) of the fetched resource including the response header fields plus the response payload body.
The encodedBodySize
property returns the size (in octets) received from the fetch (HTTP or cahce), of the payload body, before removing any applied content-codings. decodedBodySize
returns the size (in octets) received from the fetch (HTTP or cache) of the message body, after removing any applied content-codings.
Other properties
The nextHopProtocol
property returns the network protocol used to fetch the resource.
The initiatorType
property returns the type of resource that initiated the performance entry such as "css
" for a CSS resource, "xmlhttprequest
" for an XMLHttpRequest and "img
" for an image (such as a JPEG).
If the current context is a worker
, the workerStart
property can be used to obtain a DOMHighResTimeStamp
when the worker was started.
Methods
Resource Timing
includes two methods that extend the Performance
interface. The clearResourceTimings()
method removes all "resource
" type performance entries from the browser's resource performance entry buffer. The setResourceTimingBufferSize()
method sets the resource performance entry buffer size to the specified number of resource performance entries
.
The PerformanceResourceTiming
interface's toJSON()
method returns a JSON serialization of a "resource
" type performance entry
.
Implementation status
As shown in the PerformanceResourceTiming
interface's Browser Compatibility table, most of these interfaces are broadly implemented by desktop browsers. However, note that some properties have little to no implementation so see each property's Browser Compatibility section for more specific interoperability data.
To test your browser's support for these interfaces, run the perf-api-support
application.
See Also
- Resource Timing Standard; W3C Editor's Draft
- CanIUse data
- Resource Timing practical tips; Steve Souders; 2014 August 21
- Measuring network performance with Resource Timing API; Ilya Grigorik; 2013 December 11
- A Primer for Web Performance Timing APIs; Xiaoqian Wu; W3C Editor's Draft
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/resource_timing_api