Electron


Summary

BugSplat supports collection of both electron.crashReporter (native) and node.js crash reports. CrashReporter crashes are generated via Breakpad and BugSplat requires symbol files in order to calculate the call stack.

BugSplat can be configured to automatically locate Electron symbol files. If your app is packaged with electron-builder or similar you will need to upload application specific symbol files in order to see full native callstacks. 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.

Prerequisites

Before continuing with the integration please complete the following tasks:

Electron CrashReporter

Configure electron.crashReporter to post crash reports to BugSplat using the following steps. By enabling our Electron symbol support, Electron symbol files will be automatically downloaded by BugSplat. If you package your application with additional binaries you will need to upload the corresponding symbol files in order to correctly resolve call stacks. Please skip to step 3 if your app does not include additional binaries.

  1. Use the Breakpad symupload utility to upload symbol files to BugSplat. For additional information on how to upload symbols to BugSplat using symupload please check out ourBreakpad documentation.

  2. Verify that your application-specific symbol files show up on the Symbols page. Be sure to upload symbols for each released version of your application. For best results, integrate symupload into your build or release process.

  3. Add a require 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 this initialization code will need to be added to each process you wish to capture errors from:

  4. Generate a crash in one of the Electron processes to test your BugSplat integration:

  5. process.crash()
  6. Navigate to the Crashes page in BugSplat and you should see a new crash report for your application. Click the link in the Id column to see details about your crash on the Crash page:

  7. Integrating BugSplat with Electron Integrating BugSplat with Electron

Processing as Windows Native

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 or .exe files in the symbol store is what triggers the use of the Windows backend. Uploading Windows symbols can be done via our manual symbol upload page or our automated tool SendPdbs.


Node.js Configuration

  1. To collect Node.js errors in your application, run the following command in terminal or cmd at the root of your project to install BugSplat’s npm package:

  2. npm install --save bugsplat-node
  3. Require bugsplat-node at the entry point of your application (usually main.js) by adding the following code snippet:

  4. Create a new instance of the BugSplat class being sure to replace DatabaseName, AppName and the version number with the correct values for your application:

  5. 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:

  6. Add the error handler created above to uncaughtException and unhandledPromiseRejection events:

  7. 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:

  8. 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:

  9. renderer.js

    main.js

  10. Test BugSplat by throwing a new error in either the main or renderer process:

  11. Navigate to the Crashes page in BugSplat and you should see a new crash report for the application you just configured. Click the link in the ID column to see details about your crash on the Crash page:

  12. Integrating BugSplat with Electron Integrating BugSplat with Electron

That’s it! Your Electron application is now configured to post crash reports to BugSplat.

Node.js API


In addition to the configuration demonstrated above, there are a few public methods that can be used to customize your BugSplat integration:

Contributing


BugSplat loves open source software! If you have suggestions on how we can improve this integration, please reach out to support@bugsplat.com, create an issue in our GitHub repo or send us a pull request.