# shield-study-js-errors

**Repository Path**: mirrors_mozilla/shield-study-js-errors

## Basic Information

- **Project Name**: shield-study-js-errors
- **Description**: INACTIVE - http://mzl.la/ghe-archive - A study to test collecting JavaScript errors thrown by Firefox chrome code
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-22
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Shield Study: JavaScript Errors
A [Shield study][] to test collecting JavaScript errors thrown by Firefox
chrome code (__not__ errors from webpages themselves).

[Shield study]: https://wiki.mozilla.org/Firefox/SHIELD

## Overview
This study listens for browser chrome errors being logged to the Browser
Console. It then computes a hash based on the error type, name, and stack
trace, and sends that hash in a `shield-study-addon` Telemetry ping along with
the user's client ID and environment information.

The purpose of the study is to measure the amount and distribution of browser
chrome errors in a privacy-respectful way. The data will be used to create a
prototype for collecting these errors to aid in Firefox development.

## Dashboards

- [Number of study pings received per-minute](https://pipeline-cep.prod.mozaws.net/dashboard_output/graphs/analysis.mkelly_mozilla_com.shield_study_js_errors_pings_received.JS_error_study_pings_per_minute.html)

## Preferences
<dl>
  <dt>
    <code>
      extensions.shield-study-js-errors@shield.mozilla.org.testing
    </code>
  </dt>
  <dd>If true, mark Telemetry pings sent by the client as test pings.</dd>
  <dt>
    <code>
      extensions.shield-study-js-errors@shield.mozilla.org.submitIntervalMs
    </code>
  </dt>
  <dd>
    Interval (in milliseconds) at which to submit collected error hashes to
    telemetry.
  </dd>
  <dt>
    <code>
      extensions.shield-study-js-errors@shield.mozilla.org.expirationDate
    </code>
  </dt>
  <dd>
    Date.parse-compatible string specifying the datetime that the experiment
    should expire and automatically uninstall itself. Defaults to January 1st,
    2018.
  </dd>
  <dt>
    <code>
      extensions.shield-study-js-errors@shield.mozilla.org.expirationIntervalMs
    </code>
  </dt>
  <dd>
    Interval (in milliseconds) at which to check whether the study has expired or not. Defaults to once per day.
  </dd>
</dl>

## Data Collection
The study collects errors by listening to all messages that are being logged to
the [Browser console][] and filtering out non-error messages. Then, it filters
out errors with [categories that the Web console displays][categories], leaving
only errors from the Firefox UI itself.

### Telemetry Ping Example
Once an hour, if any errors were captured, a [Telemetry][] ping is sent with
[environmental data][] and a payload that looks like this:

```json
{
  "version": 3,
  "study_name": "shield-study-js-errors",
  "branch": "default",
  "addon_version": "0.1.0",
  "shield_version": "unset",
  "type": "shield-study-addon",
  "data": {
    "attributes": {
      "fingerprints": "[{\"fingerprint\":\"q35iauGpeCg8FIHj4ptetoBxjIdkuyQi2InIkNpd3AYLwSH7RS44By4CbrPVH0yA\",\"utcTimestampMs\":1512683455924}]",
      "utcTimestampMs": "1512683575918"
    }
  },
  "testing": false
}
```

The study specific fields are:

<dl>
  <dt><code>data.attributes.fingerprints</code></dt>
  <dd>
    A JSON string encoding a list of objects. Each object has a fingerprint,
    which is a SHA384 hash of the an error type, message, and stacktrace, and a
    timestamp indicating when the error occurred.
  </dd>
  <dt><code>data.attributes.utcTimestampMs</code></dt>
  <dd>
    A timestamp indicating when the ping was sent. This is used to deal with
    inaccurate local time on the client.
  </dd>
</dl>

[Browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
[categories]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIScriptError#Categories
[Telemetry]: https://wiki.mozilla.org/Telemetry
[environmental data]: http://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/data/environment.html

## Development
To build the add-on, run the `make` command:

```sh
$ make
```

This will create a `shield-study-js-errors.xpi` file in the root of the repo
containing the add-on.

To test this, you will either need to get the add-on signed by the Mozilla
Extension key, or disable the following preferences on a copy of Firefox
Nightly:

- `xpinstall.signatures.required`
- `extensions.allow-non-mpc-extensions`

Linting can be run on the add-on using `make lint`:

```sh
$ npm install # If they haven't been installed yet
$ make lint
```

## License
Shield Study: JavaScript Errors is licensed under the MPLv2. See the `LICENSE`
file for details.