Crash Reporting

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 default reporting endpoint, which will direct crash reports there:

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

dictionary CrashReportBody : ReportBody {
  DOMString reason;
  DOMString stack;
  boolean is_top_level;
  DocumentVisibilityState visibility_state;
  object crash_report_api;
};

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.

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

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.
is_top_level: A boolean representing whether the Document that crashed belonged to a top-level traversable, or not.
visibility_state: The string value "visible" or "hidden", matching the DocumentVisibilityState enum that is exposed to the web platform, via Document.visibilityState. It represents whether the visual viewport that the crashed Document was hosted in was visible at all, or fully occluded.
crash_report_api: A JSON dictionary of arbitrary key/value data obtained by deserializing the memory buffer in user agent’s crash report buffers map, identified by a crashing Document’s CrashReportContext’s backing buffer ID member. This buffer is deserialized as a JSON-formatted string, and its keys and values are appended to this any object member of the CrashReportBody.

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.

3.1. Crash Reports Delivery Priority

If a crash-reporting endpoint is specified, crash reports are delivered to it.

Otherwise, if a default endpoint is specified, crash reports are delivered to it.

If neither endpoint is specified, crash reports are not delivered.

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

4. The `CrashReportContext` interface

partial interface Window {
  readonly attribute CrashReportContext crashReport;
};

Each Window object has an associated crashReport, which is a CrashReportContext instance created alongside the Window.

The crashReport getter steps are:

If this’s relevant global object’s associated Document is not fully active, then return null.
Return this’s relevant global object’s crashReport object.

[Exposed=Window]
interface CrashReportContext {
    Promise<undefined> initialize(unsigned long long length);
    undefined set(DOMString key, DOMString value);
    undefined delete(DOMString key);
};

Each CrashReportContext object has an associated internal map, which is a map whose keys and values are both DOMStrings.

The user agent has an associated crash report buffers, which is a map whose keys are unique internal values and whose values are implementation-defined values.

Note: The internal map is a map-representation of the data that will eventually appear in a crash report, and it exists to ergonomically interact with this data via map semantics. But implementations of this specification, especially those supporting site isolation, will likely ultimately serialize its entire contents to a backing shared memory buffer tracked by the user agent’s crash report buffers map. The values of that map are expected to be those memory buffers that span the web process and whatever OS process is responsible for sending crash reports when a web process crashes, and its internal map is no longer available to read from.

Each CrashReportContext object has an associated backing buffer ID, which is a null-or-unique internal value; it is initially null.

Each CrashReportContext object has an associated is buffer initialized boolean, which is initially false.

Note: This member is asynchronously set to true when the backing memory buffer associated with this’s backing buffer ID is initialized.

Each CrashReportContext object has an associated unsigned long long buffer length, which is initially 0.

Note: This gets assigned once in initialize(), and tracks the maximum number of bytes that any call to set() can write to the memory backing internal map.

The internal map is used to hold all keys/values that will be supplied to the developer via CrashReportBodys. In browsers with site isolation, the physical process that writes to this data is different from the one that reads from it and sends the crash reports. Therefore, it is expected that implementations maintain this map as a shared memory buffer spanning the two processes. This is what the Chromium implementation of this API does.

The initialize(length) method steps are:

If this’s relevant global object’s associated Document is not fully active, then throw a new "InvalidStateError" DOMException.

Note: This will be surfaced to the user via a rejected Promise.
If this’s backing buffer ID is non-null, then throw a new "InvalidStateError" DOMException.
If length is > than 5 * 1024 * 1024, then throw a new "NotAllowedError" DOMException.

Note: The limit for the crash report memory buffer is 5 megabytes.
Set this’s buffer length to length.
Set this’s backing buffer ID to the result of creating a new unique internal value.
Let cachedThis be this.
Let promise be a a new promise.
Run these steps in parallel:
1. Let backing buffer ID be cachedThis’s backing buffer ID.
2. Run implementation-defined steps to create and initialize a backing memory store of length bytes.
3. If such a buffer was created, then:
  1. Set the user agent’s crash report buffers[backing buffer ID] to the buffer.
  2. Set cachedThis’s is buffer initialized to true.
4. Queue a global task on the DOM manipulation task source given cachedThis’s relevant global object, to resolve promise with undefined.
Return promise.

The set(key, value) method steps are:

If this’s relevant global object’s associated Document is not fully active, then throw a new "InvalidStateError" DOMException.
If this’s is buffer initialized is false, then throw a new "InvalidStateError" DOMException.

Note: This will be false both before initialize() is called, and after it is called but before its returned Promise resolves. It ensures that set() only works when the backing buffer identified by the backing buffer ID is fully initialized.
Set this’s internal map[key] to value.
Let serialization be the result of serializing a JavaScript value to JSON bytes, given this’s internal map.
If serialization’s size is > this’s buffer length, then:
1. Remove this’s internal map[key].
2. Throw a new "NotAllowedError" DOMException.
Let backing buffer ID be this’s backing buffer ID.
Write serialization to the user agent’s crash report buffers[backing buffer ID].

The delete(key) method steps are:

If this’s relevant global object’s associated Document is not fully active, then throw a new "InvalidStateError" DOMException.
If this’s is buffer initialized is false, then throw a new "InvalidStateError" DOMException.
Remove this’s internal map[key].
Let serialization be the result of serializing a JavaScript value to JSON bytes, given this’s internal map.
Let backing buffer ID be this’s backing buffer ID.
Write serialization to the user agent’s crash report buffers[backing buffer ID].

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

6. Implementation Considerations

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

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

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

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

Crash Reporting

Abstract

Status of this document

1. Introduction

1.1. Examples

2. Concepts

2.1. Crash

2.2. Out-of-Memory

2.3. Unresponsive

3. Crash Reports

3.1. Crash Reports Delivery Priority

4. The `CrashReportContext` interface

5. Document Policy Integration

6. Implementation Considerations

6.1. Delivery

7. Sample Reports

8. Security Considerations

9. Privacy Considerations

9.1. Cross-Process Contamination

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Crash Reporting

Abstract

Status of this document

1. Introduction

1.1. Examples

2. Concepts

2.1. Crash

2.2. Out-of-Memory

2.3. Unresponsive

3. Crash Reports

3.1. Crash Reports Delivery Priority

4. The CrashReportContext interface

5. Document Policy Integration

6. Implementation Considerations

6.1. Delivery

7. Sample Reports

8. Security Considerations

9. Privacy Considerations

9.1. Cross-Process Contamination

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

4. The `CrashReportContext` interface