Navigation Error Logging
W3C First Public Working Draft 11 February 2014
- This version:
- http://www.w3.org/TR/2014/WD-navigation-error-logging-20140211/
- Latest 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., <arvind@google.com>
- Jatinder Mann, Microsoft Corp., <jmann@microsoft.com>
- Alois Reitbauer, Compuware Corp., <alois.reitbauer@compuware.com>
Copyright
© 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C
liability,
trademark
and document
use rules apply.
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 document is the First Public Working Draft of the Navigation Error Logging specification.
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 First Public 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
Introduction
- 2
Conformance requirements
- 3 Terminology
- 4 Navigation Error Logging
- 4.1 Introduction
- 4.2 The
NavigationErrorEntry interface
- 4.3 Extensions to the
Performance Interface
- 4.4 Monotonic Clock
- 5 Privacy and Security
- 6 References
- 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 onNavigationErrorsReceived(errorList) {
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 init()
{
window.performance.getNavigationErrors(onNavigationErrorsReceived);
}
</script>
</body>
</html>
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.
partial interface Performance {
void enableNavigationErrorReporting(DOMString reportUrl);
void disableNavigationErrorReporting();
void enableNavigationErrorLogging(boolean enable);
void getNavigationErrors(GetNavigationErrorsCallback getnavigationerrorscallback);
void clearNavigationErrors();
typedef sequence <NavigationErrorEntry> NavigationErrorEntryList;
};
callback GetNavigationErrorsCallback = void (NavigationErrorEntryList navigationerrorentrylist);
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
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
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
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.