Web Timing

Working Draft September 26th, 2009

This version:

http://example.com/

Latest version:

http://example.com/

Previous versions:

http://example.com/

Editors:

Zhiheng Wang, Google Inc.,

Copyright 2009, All Rights Reserved

Abstract

This specification defines an interface for web applications to access timing information.

Status of this document

This is a work in progress and may change without any notices.

If you wish to make comments regarding this document, please send them to zhihengw@google.com. All feedback is welcome.

Table of Contents

Introduction

This section is non-normative

User latency is an important quality benchmark for Web Applications. While JavaScript-based mechanisms can provide comprehensive instrumentations for user latency measurements within an application, in many cases, they are unable to provide a complete end-to-end latency picture.

For example, the following Javascript shows the time it take to fully load a page: 

 
<html>
<head>
<script type="text/javascript">
var start = new Date().getTime();
function onLoad() {
  var now = new Date().getTime();
  var latency = now - start;
  alert("page loading time: " + latency);
}
<script>
</head>
<body onload="onLoad()">
<!- Main page body goes from here. -->
</body>
</html>

The script calculates the time it takes to load the page after the first bit of JavaScript in the head is executed, but it does not give any information about the time it takes to get the page from the server.

To address the need for complete information on the user experience, this document introduces the Timing interface. This interface allows JavaScript mechanisms to provide complete client-side latency measurements within applications. With the proposed interface, the previous example could be modified to provide information about user's perceived page load time.

The following script calculates how much time has elapsed since the occurance of a navigation event, such as the mouse click on a link. 

 
<html>
<head>
<script type="text/javascript">
function onLoad() {
  var now = new Date().getTime();
  var latency = now - window.pageTiming.navigationTime;
  alert("User-perceived page loading time: " + latency);
}
<script>
</head>
<body onload="onLoad()">
<!- Main page body goes from here. -->
</body>
</html>

Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core specifications. [DOM3CORE]

A DOM attribute is said to be getting when its value is being retrieved (such as by author script), and is said to be setting when a new value is assigned to it.

The term "JavaScript" is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known. [ECMA262]

Web Application Timing

Introduction

This section is non-normative

This specification introduces an interface that provides Web applications with timing-related information. This specification does not cover how Web applications leverage these interfaces to collect, store and report the provided information.

The Timing interface

interface Timing {
  const unsigned short NAVIGATION_LINK = 0;
  const unsigned short NAVIGATION_REDIRECT_SERVER = 1;
  const unsigned short NAVIGATION_REDIRECT_META = 2;
  const unsigned short NAVIGATION_REDIRECT_ONLOAD = 3;
  const unsigned short NAVIGATION_REDIRECT_JAVASCRIPT = 4;
  const unsigned short NAVIGATION_FORWARD_BACK = 5;
  const unsigned short NAVIGATION_USER_BROWSER = 6;
  const unsigned short NAVIGATION_NEW_WINDOW = 7;
  const unsigned short NAVIGATION_RELOAD = 8;
  const unsigned short NAVIGATION_IFRAME = 9;
  const unsigned short NAVIGATION_OTHER = 15;
 
  readonly attribute unsigned short navigationType;
 
  readonly attribute unsigned double navigationTime;
 
  readonly attribute unsigned double redirectionTime;
 
  readonly attribute unsigned float domainLookupTime;
};

The navigationType attribute

The navigationType attribute must return the type of the last navigation event of the current document. It must have one of the following values:

NAVIGATION_LINK: navigation started by clicking on a link on the previous page.

TRANSITION_REDIRECT_SERVER: Navigation is any of 30x server redirections.

NAVIGATION_REDIRECT_META: Client meta-refresh header redirection.

NAVIGATION_REDIRECT_ONLOAD: Client onload redirection

NAVIGATION_REDIRECT_JAVASCRIPT: Javascript redirection.

NAVIGATION_FORWARD_BACK: Navigation through a forward or backward operation.

NAVIGATION_USER_BROWSER: Navigation by typing a url into the user agent's address bar.

NAVIGATION_NEW_WINDOW: Current page is opened in a tab or window by the user agent.

NAVIGATION_RELOAD: Navigation through the reload operation.

NAVIGATION_IFRAME: Navigation is initiated within an iframe.

NAVIGATION_OTHER: Any other navigation types not defined by other values.

In top-level browsing context, the navigationType must not return NAVIGATION_IFRAME. In case the current browsing context resides within an iframe, the navigationType must return NAVIGATION_IFRAME.

The navigationTime attribute

navigationTime must return the number of milliseconds between midnight of January 1, 1970 (UTC) and the time when the last navigation event was initiated.

Example

Different user agents may use different events to signal the start of navigation, for example

The redirectionTime attribute

redirectionTime must return the number of elapsed milliseconds between midnight of January 1, 1970 (UTC) when the last non-server-redirection navigation event was initiated.

The domainLookupTime attribute

This attribute must return the number of milliseconds the user agent spends on domain name lookup for the current document. If the current document is retrieved from relevant application caches, this attribute must return zero.

The pageTiming attribute

interface Window {
  readonly attribute Timing pageTiming;
};

The pageTiming attribute represents the timing information related to the current browsing context. Each browsing context must have a unique pageTiming attribute.

Following is an example of how to use the interface in an HTML page: 

 
var server_response_time = window.pageTiming.navigationTime;
if (window.pageTiming.navigationType == window.pageTiming.NAVIGATION_LINK) {
  alert (server_response_time);
}

Processing model

User agents should always refresh the pageTiming attribute when a navigation event takes place, unless the navigation is aborted for any of the following reasons:

Before the user agent checks with the relevant application caches, it should carry out the following steps to create or refresh the pageTiming attribute:

If the resource is from the relevant application caches, window.pageTiming.domainLookupTime should be set to 0. Otherwise, on completion of the DNS lookup, the user agent should update the window.pageTiming.domainLookupTime attribute.

The granularity of the navigationTime, redirectionTime and domainLookupTime must be equal to or exceed the granularity of the dates and times objects.

Timing accuracy of no less than one millisecond is recommended.

Privacy

This section is non-normative.

The Timing attribute does not contain any Personal Identifiable Information (PII). There is no obvious privacy concern at this time.

Security

This section is non-normative.

The Timing attribute contains only relative timing information within the current browsing context. Information passing across browsing contexts can be implemented with Web Storage. Security concerns related to Web Storage are not discussed in this document.

Acknowledgements

I would like to thank all the people that I have been in touch with regarding this draft.