Navigation Error Logging

Editor's Draft February 12, 2014

This version:
http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/NavigationErrorLogging/Overview.html
Latest published version:
http://www.w3.org/TR/navigation-error-logging/
Latest Editor's Draft:
http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/NavigationErrorLogging/Overview.html
Editors:
Arvind Jain, Google Inc., <>
Jatinder Mann, Microsoft Corp., <> (Until February 2014)

Abstract

This specification defines an interface to store and retrieve error data related to the previous navigations of a document.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

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

Please send comments to public-web-perf@w3.org (archived) with [NavigationErrorLogging] at the start of the subject line.

This document is produced by the Web Performance Working Group. The Web Performance Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

  1. 1 Introduction
  2. 2 Conformance requirements
  3. 3 Terminology
  4. 4 Navigation Error Logging
    1. 4.1 Introduction
    2. 4.2 The NavigationErrorEntry interface
    3. 4.3 Extensions to the Performance Interface
    4. 4.4 Monotonic Clock
  5. 5 Privacy and Security
  6. 6 References
  7. Acknowledgements

1 Introduction

This section is non-normative.

Accurately measuring performance characteristics of web applications is an important aspect in helping site developers understand how to make their web applications faster. Likewise, measuring and understanding when web applications are not properly loading for end users due to network errors is an example of the worst case web browsing performance.

Today, site developers do not have real time web application availability data from their end users. Synthetic testing cannot truly provide global or near real-time availability data for real end users.

For example, a user visits http://example.com, causing the User Agent to send a HTTP request to the server. The server has a memory bug that causes a random set of responses to have a space in the middle of the HTTP response header, like so:

        HTTP/1. 1 200 OK
        Date: Thu, 24 Jan 2015 05:46:54 GMT
        Content-Length: 2291
        Content-Type: text/html
    

In this example, the seventh character of the first response, incorrectly has a space (e.g., HTTP/1. 1 should be HTTP/1.1). When the server sends this response, this causes strict format validation issues at the CDN near the user to fail to process the request. So while the server sees a 200 OK HTTP response, the end user actually sees a 500 Server Error HTTP response.

The previous example described a case where the site developers may not actually know that end users are hitting this problem for quite some time. As the issue is random, it may not be caught by synthetic testing.

To address the need for detailed information on the errors resulting from the navigation of the document, the Navigation Error Logging specification defines the NavigationErrorEntry interface. This interface allows JavaScript mechanisms to provide client-side error data on the previous navigations of the document within the applications. As it is typically impossible to obtain error data through JavaScript mechanisms during an aborted navigation due to the error, this data is persisted across sessions. The interface also allows a web developer to specify a error reporting url that the user agent can use to upload error data to in real time on a navigation error.

The following script shows how a developer can use the NavigationErrorEntry interface to obtain accurate error timing data related to the previous navigations of the document.

<!doctype html>
<html>
  <head>
  </head>
  <body onload="init()">
    <script>
       function init() 
       {
           var p = window.performance.getNavigationErrors();
           p.then(function (errorList) {
              // this is the "resolve" side of the Promise
              for (i = 0; i < errorList.length; i++)
              {
                  if (window.console) console.log("Document: "                + errorList[i].name + "\n" +
                                                  "Error Type: "              + errorList[i].errorType + "\n" +
                                                  "Time of Error (UTC): "     + new Date(errorList[i].startTime) + "\n" +
                                                  "Duration: "                + errorList[i].duration);
              }
           }, function (error) {
                // there was some system error while fetching the list of nav errors
                // i.e., this is the "reject" side of the Promise
           });
       }
    </script>
  </body>
</html>

2 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 RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.

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.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 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 "navigation" refers to the act of navigating.

The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.

4 Navigation Error Logging

4.1 Introduction

This section is non-normative.

This specification defines the NavigationErrorEntry interface to store and retrieve error data related to previous navigations of a document.

4.2 The NavigationErrorEntry interface

interface NavigationErrorEntry {
  readonly attribute DOMString name;
  readonly attribute DOMTimeStamp startTime; 
  readonly attribute DOMTimeStamp duration;
  readonly attribute NavigationErrorType errorType; 
};

enum NavigationErrorType { "dns", "tcp", "ssl", "http", "abandoned" };

name attribute

The name attribute MUST return the current address of the document where the error occurred, as an absolute URL.

startTime attribute

The startTime attribute MUST return a DOMTimeStamp with the time immediately after the user agent finishes prompting to unload the previous document while navigating to the document that resulted in an error.

duration attribute

The duration attribute MUST return a DOMTimeStamp equal to the difference between the time immediately after the User Agent logs the occurrence of the error and startTime.

errorType attribute

This attribute MUST return one of the following strings describing the type of the error: dns, tcp, ssl, http, and abandoned. The abandoned error type refers to the case where the user aborts the navigation before it is complete.

4.3 Extensions to the Performance Interface

partial interface Performance {
  void enableNavigationErrorReporting(DOMString reportUrl);
  void disableNavigationErrorReporting();
  void enableNavigationErrorLogging(boolean enable);
  Promise getNavigationErrors();
  void clearNavigationErrors();

  typedef sequence <NavigationErrorEntry> NavigationErrorEntryList;
};

enableNavigationErrorReporting method

The enableNavigationErrorReporting method, when invoked, enables reporting of future navigation errors for the origin of the current document to the resolved URL provided by the reportUrl parameter. This setting must be persisted across sessions.

When a navigation to a url in the given origin fails, the user agent MUST fetch reportUrl, with the synchronous flag not set, using HTTP method POST, with a Content-Type header field of application/json with an entity body consisting of the JSON stringification of the NavigationErrorEntry object corresponding to the failed navigation. The user agent MUST not follow redirects when fetching this and ignore the response. If the fetch of reportUrl itself fails, the user agent MUST not retry fetching reportUrl.

Parameters

in reportUrl type of DOMString

The reportUrl parameter indicates the resolved URL where the error data is to be sent. The User Agent MUST throw the URLMismatchError exception if the URL cannot be resolved.

No return value

No additional exceptions

disableNavigationErrorReporting method

The disableNavigationErrorReporting method, when invoked, disables reporting of navigation errors for the origin of the current document. This setting must be persisted across sessions.

No Parameters

No return value

No additional exceptions

enableNavigationErrorLogging method

The enableNavigationErrorLogging method, when invoked, enables or disables logging of navigation errors, based on whether enable is true or false, respectively, for the origin of the current document. This setting must be persisted across sessions.

The user agent should limit the total number of NavigationErrorEntry objects stored for a given origin. A limit of 150 entries is recommended.

Parameters

in enable type of boolean

The enable parameter enables or disables logging of navigation errors.

No return value

No additional exceptions

getNavigationErrors method

  1. Let promise be a newly-created Promise.
  2. Let errorList be the NavigationErrorEntryList object that contains a copy of all NavigationErrorEntry objects for the origin of the current document in chronological order.
  3. If errorList is created successfully, resolve promise with errorList.
  4. If errorList cannot be created, reject promise with an Error instance explaining the failure.
  5. Return promise.

No Parameters

Return value

A Promise object.

No additional exceptions

clearNavigationErrors method

The clearNavigationErrors method clears the buffer used to store the list of NavigationErrorEntry objects.

No parameters

No return value

No additional exceptions

4.4 Monotonic Clock

The value of the timing attributes must monotonically increase to ensure timing attributes are not skewed by adjustments to the system clock while recording error data. The difference between any two chronologically recorded timing attributes must never be negative.

5 Privacy and Security

This section is non-normative.

The NavigationErrorEntry interface exposes timing and other information for an error that has occurred in the previous navigations to the web page. Access to the NavigationErrorEntry interface is limited to the same origin.

The user agent mechanisms used to delete private data such as history or cookies for a given origin or as a whole should also delete the corresponding NavigationErrorEntry objects.

6 References

6.1 Normative References

[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[IETF RFC 2616]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding et al., Authors. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt.
[IETF RFC 6454]
The Web Origin Concept, Adam Barth, Author. Internet Engineering Task Force, December 2011. Available at http://www.ietf.org/rfc/rfc6454.txt.
[ECMA-262]
ECMAScript Language Specification, 5.1 Edition. ECMA International, Standard ECMA-262, June 2011. This version of the ECMAScript Language is available from http://www.ecma-international.org/publications/standards/Ecma-262.htm.
[W3C DOM4]
W3C DOM4, Anne van Kesteren, et al., Editors. World Wide Web Consortium, 4 February 2014. This version of the W3C DOM4 is http://www.w3.org/TR/dom/. The latest version of W3C DOM4 is available at http://www.w3.org/TR/dom/.
[HTML5]
HTML 5.1, Robin Berjon et al., Editors. World Wide Web Consortium, February 2014. This version of the HTML5 is available from http://www.w3.org/TR/html51/. The latest editor's draft of HTML 5.1 is available at http://www.w3.org/html/wg/drafts/html/master/.
[Web IDL]
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.

Acknowledgements

We would like to offer our sincere thanks to Aaron Heady, Daniel Austin, James Simonsen, Philippe Le Hegaret, and Jason Weber for their contributions to this work.