Electron is a popular framework allows you to build cross-platform desktop applications with Javascript and HTML. It is used by Discord, Visual Studio Code 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 publicly released versions of Electron, which means you automatically get human-readable callstacks if you are using a publicly released version of Electron.
Sign Up
If you haven't signed up already, go to https://register.backtrace.io/signup/ to create an account. From there, you'll be asked to create a project which will generate a submission token
Requirements Summary
You can use Backtrace to capture both Electron process crashes, as well as uncaught Javascript errors. The way to set these up depends on whether you're working within the main or the renderer Electron processes:
- Electron Crashes - In both the main and renderer processes, initialize Electron's crash reporter by calling
crashReporter.start
- Uncaught Javascript Errors - In the main process, initialize the
backtrace-node
library. In the renderer process, use thebacktrace-js
library.
More details on setting these up are below.
Main and Renderer Process - Reporting Electron Crashes
With your endpoint and token, 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 in the product guide collection.
Electron errors handled by Backtrace will have the following attributes populated. We recommend adding these attributes in your project:
ver
Electron versionprocess_type
main or browserplatform
OS_companyName
Populated from package.json, but can be overridden bycompanyName
passed tocrashReporter.start
_productName
Populated from package.json, but can be overridden byproductName
passed tocrashReporter.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();
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();
Main Process - Javascript Error Reporting
To capture Javascript errors in the main process, install our Node.js npm package (npm install backtrace-node).
Initialize the Backtrace reporting module with your endpoint, token, and any attributes you wish to use.
Example code:
var bt = require('backtrace-node');
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!"));
Renderer Process - Javascript Error Reporting
To capture Javascript 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 section of the product guide.
Combine this with our support for Node to have visibility into all manners of crashes and exceptions in your application.