A Primer for Web Performance Timing APIs (original) (raw)

This document introduces the basic concepts of various Web performance timing specifications, including [[PERFORMANCE-TIMELINE-2]], [[HR-TIME-2]], [[NAVIGATION-TIMING-2]], [[RESOURCE-TIMING]], [[USER-TIMING]], [[FRAME-TIMING]], [[SERVER-TIMING]], and explains how these APIs fit together.

This document is a collaboration of the W3C Web Performance Working Group. Most use cases in this document originated from the working group's past discussion, which was archived in the group's mailing list public-web-perf@w3.org and GitHub Repos.

Overview

Imagine you're visiting our W3C website, if the web content doesn't show up in the screen within a certain number of seconds, as a user, perhaps you will just close the tab and head to alternatives. However, as a developer, you might hope to trace the hints in the requests and navigation details, so that you can find out what's slowing down this webpage.

Fortunately, most browser vendors are willing to expose performance characteristics that allow developers to collect accurate performance details. These performance timing APIs, as their names suggest, are very helpful to identify the bottlenecks of the web applications from different aspects and improve the performance.

012/TR/resource-timing/{ "duration": "869.0", "tcpDuration": "441.0", "requestDuration": "423.0", "responseDuration": "3.0" } /StyleSheets/TR/W3C-WD{ "start": "886.2", "duration": "801.5" } /Icons/w3c_home{ "start": "893.9", "duration": "796.6" } /TR/reso ... view-1.png{ "start": "899.4", "duration": "1189.1", "requestDuration": "396.2", "responseDuration": "1.0" } /StyleS ... TR/logo-WD{ "start": "1695.6", "duration": "394.8" }

A Waterfall Chart generated with Page Load Waterfalls, which is using the Resource Timing API

Waterfall charts may be the first tool you'll think of when trying to understand the performance of your web applications. Have you ever wondered about the magic behind these graphic charts? In the following sections, we are going to explain a set of performance monitoring APIs that allow you to do more than a waterfall chart measurement.

Resource Timing

Fig.1 is a waterfall chart for the timing data for each loaded resource of a simple webpage. Actually, the [[RESOURCE-TIMING]] API can provide much more detail information than this. Fig.2 is a set of attributes that developers are able to access for each loaded resource on their Web applications.

Resource Timing attributes

Load Times for Resources

Web Applications mostly consist of a set of downloadable resources. Here resources usually refer to HTML documents, XHR objects, links (such as a stylesheet) or SVG elements.

The Resources Timing data are exposed as methods on the global window.performance object, which we are going to talk about in the next section. You're encouraged to use the performance.getEntriesByType("resource") method to obtain an array of Resource Timing Objects for each requested resource.

Demo of Resource Timing Details

The PerformanceResourceTiming interface extends the PerformanceEntry interface in the Performance Timeline. The attribute in Resource Timing can be measured as the difference between responseEnd and startTime.

As shown in Fig.2 and Fig.3, you are able to access a set of critical network timing attributes for each resource on the page.

Each of these timestamps is in microseconds, which are provided by the window.performance.now() method in the High Resolution Time specification.

Example

As an example, let's try to measure the time it takes to fetch the icon on the W3C homepage.