Crash Reporting

1. Introduction

[INTRODUCTION GOES HERE]

1.1. Examples

Reporting-Endpoints: default="https://example.com/reports"

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;
  readonly attribute DOMString? stack;
};

A crash report's body, represented in JavaScript by CrashReportBody, contains the following fields:

• reason: A more specific classification of the type of crash that occured, if known, or omitted otherwise. The valid reason strings are shown below.

• stack: The string representation of the JavaScript call stack at the time of the crash, if all of the following are true, or omitted otherwise:

  • The crash reason is "unresponsive".

  • The policy value for include-js-call-stacks-in-crash-reports in the Document which crashed is true.

  • The call stack can be recovered from the crashed document.

  The string representation used for stack is the same as that used by the Error.prototype.stack property.

Note: Crash reports are always delivered to the endpoint 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 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. Document Policy Integration

Site authors may opt in to recording the JavaScript call stack with some reports.

This spec defines a configuration point with the name include-js-call-stacks-in-crash-reports. Its type is boolean, and its default value is false. When configured as true in a Document for which crash reporting is enabled, this will cause a string representation of the JavaScript call stack, at the time of the crash, to be included in a crash report.

Document-Policy: include-js-call-stacks-in-crash-reports

5. Implementation Considerations

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

6. 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"
  }
}]

7. Security Considerations

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

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

8. Privacy Considerations

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

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

8.1. Cross-Process Contamination