Abstract

This specification defines a set of APIs 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 importing 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 due to the missing latency pieces. This document introduces a set of timing APIs aiming to provide the missing pieces from the user agents.

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 (e.g. 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 a set of of browser interfaces that provide 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 of the current document. Its possible values must include:

1. NAVIGATION_LINK: navigation start by clicking on a link on the previous page.
2. TRANSITION_REDIRECT_SERVER: including 30x server redirection types.
3. NAVIGATION_REDIRECT_META: client meta-refresh header redirection.
4. NAVIGATION_REDIRECT_ONLOAD: client onload redirection
5. NAVIGATION_FORWARD_BACK: navigation through browser forward and backward operations.
6. NAVIGATION_USER_BROWSER: navigation through input url.
7. NAVIGATION_REDIRECT_JAVASCRIPT: Javascript redirection.
8. NAVIGATION_NEW_WINDOW: current page is opened in a new browser, including pop-ups.
9. NAVIGATION_RELOAD: navigation through browser reload operations.
10. NAVIGATION_IFRAME: navigation is initiated within an iframe.
11. NAVIGATION_OTHER: any other navigation types that are not defined by other values.

In case the current browsing context resides within an iframe, the navigationType associated with this context should always return NAVIGATION_IFRAME. navigationType associated with the top-level browsing context should not return NAVIGATION_IFRAME.

The navigationTime attribute

navigationTime must return the number of elapsed milliseconds since midnight of January 1, 1970 (UTC) when the last navigation is initiated.

The redirectionTime attribute

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

The domainLookupTime attribute

This attribute must return the number of milliseconds the browser 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.

Processing model

User agents should always refresh the pageTiming attribute during a navigation unless the navigation is aborted for any of the following reasons:

• The navigation is caused by fragment identifiers.
• The new resource is to be handled by some sort of inline content.
• The new resource is to be handled using a mechanism that does not affect the browsing context.

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

• The user agent should determine the type of the navigation and set the window.pageTiming.navigationType attribute to the appropriate values.
• The user agent should set the window.pageTiming.navigationTime to the elapsed milliseconds since midnight of January 1, 1970 (UTC).
• If the navigation is not initiated by a HTTP 300 response code, the user agent should also set window.pageTiming.redirectionTime to the elapsed milliseconds since midnight of January 1, 1970 (UTC).

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 accuracy of the navigationTime, redirectionTime and domainLookupTime may depend on the clock of the system that the browser resides on, but it must not be less accurate than 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 PII information and 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. Passing information across browsing context can be implemented with the Web Storage. Security concerns related to Web Storage is not discussed in this document.

Acknowledgements

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