index.bs

<pre class="metadata">
Title: Crash Reporting
Status: CG-DRAFT
ED: https://wicg.github.io/crash-reporting/
Shortname: crash-reporting
Group: WICG
Editor: Ian Clelland 76841, Google Inc., iclelland@google.com
Abstract:
  This document defines mechanism for reporing browser crashes to site owners
  through the use of the Reporting API.
Level: 1
Indent: 2
Version History: https://github.com/WICG/crash-reporting/commits/gh-pages
Boilerplate: omit conformance, omit feedback-header
!Participate: <a href="https://github.com/WICG/crash-reporting/issues/new">File an issue</a> (<a href="https://github.com/WICG/crash-reporting/issues">open issues</a>)
Markup Shorthands: css off, markdown on
Include MDN Panels: no
</pre>
<pre class="anchors">
url: https://tc39.es/proposal-error-stacks/#sec-get-error.prototype-stack; type: dfn; spec: ERROR STACKS
  text: Error.prototype.stack
</pre>

Introduction {#intro}
============

[INTRODUCTION GOES HERE]


Examples {#examples}
--------

<div class="example">
  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:

  <pre>
    Reporting-Endpoints: default="https://example.com/reports"
  </pre>
</div>


Concepts {#concept}
========

Crash {#concept-crash}
-----

Out-of-Memory {#concept-oom}
-------------

Unresponsive {#concept-unresponsive}
------------


Crash Reports {#crash-report}
=============

<dfn>Crash reports</dfn> 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".

<xmp class="idl exclude">
[Exposed=(Window,Worker)]
interface CrashReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString? reason;
  readonly attribute DOMString? stack;
};
</xmp>

A [=crash report=]'s [=report/body=], represented in JavaScript by
{{CrashReportBody}}, contains the following fields:

* <dfn for="CrashReportBody">reason</dfn>: A more specific classification of the
  type of crash that occured, if known, or omitted otherwise. The valid
  <a>reason</a> strings are shown below.

<table border=1 cellpadding=5px style="border-collapse: collapse;">
  <tbody>
    <tr>
      <th><a>Reason</a></th>
      <th>Description</th>
    </tr>
    <tr>
      <td>oom</td>
      <td>The page ran out of memory.</td>
    </tr>
    <tr>
      <td>unresponsive</td>
      <td>The page was killed due to being unresponsive.</td>
    </tr>
  </tbody>
</table>

* <dfn for="CrashReportBody">stack</dfn>: 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 [=CrashReportBody/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.

Document Policy Integration {#document-policy}
===========================

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.

<div class="example">
<xmp class="http">Document-Policy: include-js-call-stacks-in-crash-reports</xmp>
</div>

Implementation Considerations {#implementation}
=============================

Delivery {#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.


Sample Reports {#sample-reports}
==============

<div class="example">
<pre>
    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"
      }
    }]
</pre>
</div>


Security Considerations {#security}
=======================

For a discussion of security considerations surrounding out-of-band reporting in
general, see [[REPORTING#security]].

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


Privacy Considerations {#privacy}
======================

For a discussion of privacy considerations surrounding out-of-band reporting in
general, see [[REPORTING#privacy]].

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

Cross-Process Contamination {#cross-process-contamination}
---------------------------