Electron

electron popular framework allows you to build cross-platform desktop applications with Javascript and HTML. It is used by Discord, Visual Studio and more. The Electron homepage can be found at https://electron.atom.io/.

Backtrace has first-class support for the crash dump format of ELectron apps, minidumps. Backtrace also dynamically downloads symbols for publically released versions of Electron, which means you automatically get human-readable callstacks if you are using a publically released version of Electron.

Sign Up

If you haven't signed up already, go to https://backtrace.io/create to create an account. From there, you'll be asked to create a project which will generate a submission token

Main Process - Enable crash reporting

Now you have everything you need to submit a dump file. Just ensure that you call electron.crashReporter.start in your application to have crashes automatically routed to Backtrace. submitURL needs to point to your Backtrace instance and must include the format and token query string parameters. See below for a self-contained example of submitting to a Backtrace-hosted instance of Backtrace.

const {crashReporter} = require('electron');

crashReporter.start({
  productName: 'iProduct',
  companyName: 'My Company, Inc.',
  submitURL: 'https://mycompany.sp.backtrace.io:6098/post?format=minidump&token=fff016fe152941145a880720158dbca39c0f1b524c96bbd7c95a896556284076',
  uploadToServer: true
});

process.crash();

Additional Attributes and Parameters

Attributes are an easy way to characterize crash reports with relevant tags. This can be incredibly useful if you want to embed additional context of the crash and later group or search on these tags. For example, you may want to tag a crash report with a version. More information on attributes can be found here

Electron errors handled by Backtrace will have the following attributes populated. We recommend adding these attributes in your project:

Attribute Description
ver Electron version
process_type mainor browser
platform OS
_companyName Populated from package.json, but can be overridden by companyNamepassed to crashReporter.start
_productName Populated from package.json, but can be overridden by productNamepassed to crashReporter.start
_version This is populated from version in the application's package.json file

There are two ways to include additional attributes with your crash reports. However, the second method is only available on MacOS presently.

Windows/Linux/MacOS - Use the extra option on crashReporter.start

When calling crashReporter.start, you can provide an optional parameter extra. The keys of this object will be your attribute names, and their values are passed along accordingly.

If you are using this method and need to change or add attributes after first calling crashReporter.start, you will need to call it again.

const {crashReporter} = require('electron');

crashReporter.start({
  productName: 'iProduct',
  companyName: 'My Company, Inc.',
  submitURL: 'https://mycompany.sp.backtrace.io:6098/post?format=minidump&token=fff016fe152941145a880720158dbca39c0f1b524c96bbd7c95a896556284076',
  uploadToServer: true,
  extra: {
    "version": "1.0.1",
    "datacenter": "nyc"
  }
});

process.crash();

MacOS Only - Using setExtraParameter

On MacOS, you can also use crashReporter.setExtraParameter to add additional attributes to your Electron crash reports.

const {crashReporter} = require('electron');

crashReporter.start({
  productName: 'iProduct',
  companyName: 'My Company, Inc.',
  submitURL: 'https://mycompany.sp.backtrace.io:6098/post?format=minidump&token=fff016fe152941145a880720158dbca39c0f1b524c96bbd7c95a896556284076',
  uploadToServer: true
});

crashReporter.setExtraParameter("version", "1.0.1")
crashReporter.setExtraParameter("datacenter", "nyc")

process.crash();

Renderer Process - Enable Crash Reporting

To capture errors in the renderer process, install our JavaScript npm package (npm install backtrace-js).

Initialize the Backtrace reporting module with your endpoint, token, and any attributes you wish to use.

Example code:

var bt = require('backtrace-js');
bt.initialize({
  endpoint: "https://yourcompany.sp.backtrace.io:6098",
  token: "fffab125f8907f0e70bf5efdf4a7ec78163e055df8d8ddd291e2243515488194aaa",
  attributes: {
      'datacenter': 'nyc',
      'version': '1.0.3'
  }
});

// Backtrace creates reports from your uncaught exceptions automatically.
// If you wish to send a report manually:

bt.report(new Error("Something failed!"));

Additional Symbols

If you require additional symbols, please see the symbolification guide.

Combine this with our support for Node to have visibility into all manners of crashes and exceptions in your application.

FAQ

Ensure submission token exists

First step is to ensure you have a submission token created.

Ensure listener exists

Next step is to ensure that a listener exists for submitting crash data. Look for listeners with the http/writer label. Listener settings are found under the Configuration Organization menu item.

In the above example, if the server is hosted at testing.company.com, then we are able to submit dump files to either http://testing.company.com:6097/post or https://testing.company.com:6098/post. These are the first two entries in the above screenshot, with the http/writer labels. These also happen to be the default settings if you are using a Backtrace-hosted instance.