0

Update docs on JavaScript error reporting

Update docs on JavaScript error reporting and address some points of
confusion:

* Update to note that this system will work with TypeScript as well
* Update to note that Lacros is supported
* Corrected information about how the magic signature is generated
* Try to resolve some confusion around JavaScript errors being called
  "crashes" by some tooling, and people thinking they were actually
  crashing the renderer
* Explained why "how serious is this error report?" is difficult to
  answer.

BUG=None

Change-Id: I9600bdf947f375ea4a969769561d7d84cc03c888
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3543914
Reviewed-by: Demetrios Papadopoulos <dpapad@chromium.org>
Commit-Queue: Ian Barkley-Yeung <iby@chromium.org>
Cr-Commit-Position: refs/heads/main@{#985089}
This commit is contained in:
Ian Barkley-Yeung
2022-03-25 00:00:44 +00:00
committed by Chromium LUCI CQ
parent ea5a561617
commit 4340462613

@ -892,25 +892,37 @@ therefore it is not advisable to use for any sensitive content.
## JavaScript Error Reporting
By default, errors in the JavaScript of a WebUI page will generate error reports
which appear in Google's internal crash/ reports page. These error reports will
only be generated for Google Chrome builds, not Chromium or other Chromium-based
browsers.
By default, errors in the JavaScript or TypeScript of a WebUI page will generate
error reports which appear in Google's internal [go/crash](http://go/crash)
reports page. These error reports will only be generated for Google Chrome
builds, not Chromium or other Chromium-based browsers.
Specifically, an error report will be generated when the JavaScript for a
WebUI-based chrome:// page does one of the following:
Specifically, an error report will be generated when the JavaScript or
TypeScript for a WebUI-based chrome:// page does one of the following:
* Generates an uncaught exception,
* Has a promise which is rejected, and no rejection handler is provided, or
* Calls `console.error()`.
Such errors will appear alongside other crashes in the
`product_name=Chrome_ChromeOS` or `product_name=Chrome_Linux` lists on crash/.
The signature of the error is simply the error message. To avoid
spamming the system, only one error report with a given message will be
`product_name=Chrome_ChromeOS`, `product_name=Chrome_Lacros`, or
`product_name=Chrome_Linux` lists on [go/crash](http://go/crash).
The signature of the error is the error message followed by the URL on which the
error appeared. For example, if chrome://settings/lazy_load.js throws a
TypeError with a message `Cannot read properties of null (reading 'select')` and
does not catch it, the magic signature would be
```
Uncaught TypeError: Cannot read properties of null (reading 'select') (chrome://settings)
```
To avoid spamming the system, only one error report with a given message will be
generated per hour.
If you are getting error reports for an expected condition, you can turn off the
reports simply by changing `console.error()` into `console.warn()`.
reports simply by changing `console.error()` into `console.warn()`. For
instance, if JavaScript is calling `console.error()` when the user tries to
connect to an unavailable WiFi network at the same time the page shows the user
an error message, the `console.error()` should be replaced with a
`console.warn()`.
If you wish to get more control of the JavaScript error messages, for example
to change the product name or to add additional data, you may wish to switch to
@ -918,8 +930,28 @@ using `CrashReportPrivate.reportError()`. If you do so, be sure to override
`WebUIController::IsJavascriptErrorReportingEnabled()` to return false for your
page; this will avoid generating redundant error reports.
Known issues:
1. Error reporting is currently enabled only on ChromeOS and Linux.
### Are JavaScript errors actually crashes?
JavaScript errors are not "crashes" in the C++ sense. They do not stop a process
from running, they do not cause a "sad tab" page. Some tooling refers to them as
crashes because they are going through the same pipeline as the C++ crashes, and
that pipeline was originally designed to handle crashes.
### How much impact does this JavaScript error have?
That depends on the JavaScript error. In some cases, the errors have no user
impact; for instance, the "unavailable WiFi network calling `console.error()`"
example above. In other cases, JavaScript errors may be serious errors that
block the user from completing critical user journeys. For example, if the
JavaScript is supposed to un-hide one of several variants of settings page, but
the JavaScript has an unhandled exception before un-hiding any of them, then
the user will see a blank page and be unable to change that setting.
Because it is difficult to automatically determine the severity of a given
error, JavaScript errors are currently all classified as "WARNING" level when
computing stability metrics.
### Known issues
1. Error reporting is currently enabled only on ChromeOS (ash and Lacros) and
Linux.
2. Errors are only reported for chrome:// URLs.
3. Unhandled promise rejections do not have a good stack.
4. The line numbers and column numbers in the stacks are for the minified
@ -929,7 +961,6 @@ Known issues:
error message includes the name of a network, each network name will be its
own signature.
## See also
* WebUI's C++ code follows the [Chromium C++ styleguide](../styleguide/c++/c++.md).