Electron
BugSplat supports the collection of both electron.crashReporter (native) and node.js crash reports. Native crashes are generated via Crashpad and BugSplat requires symbol files in order to calculate the call stack.
BugSplat will automatically resolve Electron framework symbol files when calculating call stacks. However if your application includes native add-ons or is packaged with electron-builder you will need to upload application-specific symbol files in order to see full native call stacks. All symbol files must be uploaded to BugSplat via symupload. More information about uploading symbol files to BugSplat can be found here.
BugSplat-node can also be used to collect uncaughtException and unhandledRejection events in your application's JavaScript code.
Configure electron.crashReporter to upload crash reports to BugSplat using the following steps. Electron and Electron Framework symbol files will be automatically downloaded by BugSplat. If your application uses Native Node Modules you will need to generate and upload symbol files in order to correctly resolve call stacks.
Add a build step to generate and upload
.sym files for you Node Native Modules. To generate symbol files you can run dump_syms with a path to a .node file after the Node Native Module build or rebuild step if you're using a tool like electron-rebuild.Once you've generated a
.sym file for your .node native module, the .sym file can be uploaded with either @bugsplat/symbol-upload, symupload, or manually via the Versions page.Verify that your Node Native Module
.sym files show up on the Versions page. Be sure to upload symbols for each released version of your application. For best results, integrate @bugsplat/symbol-upload or symupload into your build and release processes.Add a
require or an import statement for electron and call electron.crashReporter.start as shown in the example below. Replace company name, product name, database name, application key, user email, and comment.Note that the
globalExtra fields will be sent with crashes captured on all processes:const electron = require('electron')
electron.crashReporter.start({
companyName: '<<company name>>',
productName: '<<product name>>',
submitURL: 'https://<<database name>>.bugsplat.com/post/electron/crash.php',
compress: true,
ignoreSystemCrashHandler: true,
rateLimit: false,
globalExtra: {
'key': '<<application key>>',
'email': '<<user email>>',
'comments': '<<comment>>'
}
})
For more information on how to configure
electron.crashReporter including adding properties to individual processes, please see the Electron crashReporter documentation.Generate a crash in one of the Electron processes to test your BugSplat integration:
process.crash()
Crash Reporter Crashes
Crash Reporter Crash
BugSplat can process Breakpad crashes reported from Windows operating systems with our Windows backend, rather than the Breakpad backend. The advantage to this approach is that BugSplat will be able to display function arguments and local variables for each resolved stack frame. Another advantage of this approach is that our backend will automatically resolve Windows OS symbols.
To configure your Breakpad crashes to be processed by our Windows backend, create unique AppName/AppVersion combinations for the Windows versions of your application and upload
.pdb, .dll, and .exe files (rather than .sym files). The presence of .pdb, .dll, and .exe files in the symbol store is what triggers the use of the Windows backend. Uploading Windows symbols can be done via the Versions page or our automated tool SendPdbs.To configure reporting of JavaScript or TypeScript errors in your main and renderer processes please see our Node.js documentation to install and configure bugsplat-node.
Once you've installed bugsplat-node, create an error handler for uncaughtExceptions and unhandledPromise rejections. We recommend you quit your application in the event of an uncaughtException or unhandledPromiseRejection. You may also want to add code to display a message to your user here:
const javaScriptErrorHandler = async (error) => {
await bugsplat.post(error);
app.quit();
}
Add the error handler created above to uncaughtException and unhandledPromiseRejection events:
process.on('unhandledRejection', javaScriptErrorHandler)
process.on('uncaughtException', javaScriptErrorHandler)
Many Electron applications run multiple Node.js processes. For instance, the electron-quick-start application runs both a main and a renderer process. You will need to require bugsplat in each process you want to capture errors. To capture errors in the renderer process, add the following to renderer.js:
Sometimes it is desirable to reload or quit the application when an error occurs in the renderer process. The following is an example of how to invoke the main process from the renderer and quit your application in the case of an unhandled exception in the renderer:
window.onerror = async (messageOrEvent, source, lineno, colno, error) => {
await bugsplat.post(error)
ipcRenderer.send('rendererCrash')
}
import { ipcMain } from "electron";
ipcMain.on('rendererCrash', function () {
// Display an error and reload or quit the app here
})
Test BugSplat by throwing a new error in either the main or renderer process:
throw new Error("BugSplat!");
Node.js Crashes
Node.js Crash
That’s it! Your Electron application is now configured to post crash reports to BugSplat.
In addition to the configuration demonstrated above, there are a few public methods that can be used to customize your BugSplat integration:
bugsplat.setDefaultAppKey(appKey); // Additional metadata that can be queried via BugSplat's web application
bugsplat.setDefaultUser(user); // The name or id of your user
bugsplat.setDefaultEmail(email); // The email of your user
bugsplat.setDefaultDescription(description); // A description placeholder that can be overridden at crash time
bugsplat.setDefaultAdditionalFilePaths([paths]); // Paths to files to be sent to BugSplat at post time (limit 1MB)
bugsplat.postAndExit(error, options); // Wrapper for post that calls process.exit(1) after posting error to BugSplat
bugsplat.post(error, options); // Aysnc function that posts an arbitrary Error object to BugSplat
// If the values options.appKey, options.user, options.email, options.description, options.additionalFilePaths are set the corresponding default values will be overwritten
// Returns a promise that resolves with properties: error (if there was an error posting to BugSplat), response (the response from the BugSplat crash post API), and original (the error passed by bugsplat.post)
BugSplat has the ability to map uglified and minified JavaScript function names, file names, and line numbers back to their original values via source maps. For information on how to configure your application to upload source maps to BugSplat, please see the link below.
BugSplat loves open source software! If you have suggestions on how we can improve this integration, please reach out to [email protected], create an issue in our GitHub repo or send us a pull request.
Last modified 3mo ago