Crash Reporting

Editor’s Draft,

This version:
https://wicg.github.io/crash-reporting/
Version History:
https://github.com/WICG/crash-reporting/commits/gh-pages
Editor:
(Google Inc.)
Participate:
File an issue (open issues)

Abstract

This document defines mechanism for reporing browser crashes to site owners through the use of the Reporting API.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

[INTRODUCTION GOES HERE]

1.1. Examples

Unstable, Inc. wants to understand better how often its website is crashing in the wild. It can do this by delivering the following header to define a reporting endpoint, and direct crash reports to it:
Report-To: { "group": "default",
             "max_age": 10886400,
             "endpoints": [
               { "url": "https://example.com/reports", "priority": 1 },
               { "url": "https://backup.com/reports", "priority": 2 }
             ] }

2. Concepts

2.1. Crash

2.2. Out-of-Memory

2.3. Unresponsive

3. Crash Reports

Crash reports indicate that the user was unable to continue using the page because the browser (or one of its processes necessary for the page) crashed. For security reasons, no details of the crash are communicated except for a unique identifier (which can be interpreted by the browser vendor), and optionally the reason for the crash (such as "oom").

Crash reports are a type of report.

Crash reports have the report type "crash".

[Exposed=(Window,Worker)]
interface CrashReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString? reason;
};

A crash report’s body, represented in JavaScript by CrashReportBody, contains the following field:

Reason Description
oom The page ran out of memory.
unresponsive The page was killed due to being unresponsive.

Note: Crash reports are always delivered to the endpoint group named default; there is currently no way to override this. If you want to receive other kinds of reports, but not crash reports, make sure to use a different name for the endpoint group that you choose for those reports.

Note: Crash reports are not observable to JavaScript, as the page which would receive them is, by definition, not able to. The IDL description of CrashReportBody exists in this spec to provide a JSON-seriaizable interface whose serialization can be embedded in the out-of-band reports.

4. Implementation Considerations

4.1. Delivery

[REPORTING], which defines the framework on which this specification depends, provides at most a best-efforts delivery mechanism. This is especially true when it comes to reporting crashes. There are probably always going to be certain crash conditions which simply cannot be reported on (for instance, if the crash occurs within the crash-monitoring code of the user agent, or if the computer hosting the user agent were to suddenly cease to exist). However, many crashes can be observed by modern browsers, and their immediate causes can be deduced.

A user agent implementing crash reports SHOULD attempt to monitor documents for crashes in a way that will continue to function even when the process which is responsible for that document crashes, or is terminated by the operating system.

There are multiple ways to implement such a monitor, with varying levels of reliability and robustness to specific crash causes, and this specification does not attempt to prescribe any particular such method.

5. Sample Reports

POST /reports HTTP/1.1
Host: example.com
...
Content-Type: application/reports+json

[{
  "type": "crash",
  "age": 42,
  "url": "https://example.com/",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
  "body": {
    "reason": "oom"
  }
}]

6. Security Considerations

For a discussion of security considerations surrounding out-of-band reporting in general, see Reporting API §security.

The remainder of this section discusses security considerations for crash reporting specifically.

7. Privacy Considerations

For a discussion of privacy considerations surrounding out-of-band reporting in general, see Reporting API §privacy.

The remainder of this section discusses privacy considerations for crash reporting specifically.

7.1. Cross-Process Contamination

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[REPORTING]
Reporting API. cg-draft. URL: https://wicg.github.io/reporting/
[REPORTING-1]
Douglas Creager; et al. Reporting API. 25 September 2018. WD. URL: https://www.w3.org/TR/reporting-1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[Exposed=(Window,Worker)]
interface CrashReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString? reason;
};