Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Update electron docs #1241

Merged
merged 4 commits into from
Mar 13, 2018
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 42 additions & 46 deletions docs/integrations/electron.rst
Original file line number Diff line number Diff line change
@@ -1,73 +1,69 @@
Electron
========

To use Sentry with your Electron application, you will need to use both Raven.js SDKs, one for Browser and one for Node.js.
Browser SDK is used to report all errors from Electron's ``renderer process``, while Node.js is used to report ``main process`` errors.
This is the documentation for our new Electron SDK.
`Sentry Wizard <https://github.com/getsentry/sentry-wizard>`_ helps you with the correct
setup. Under the hood we use `raven-node <https://github.com/getsentry/raven-node>`_
and `raven-js <https://github.com/getsentry/raven-js>`_.

On its own, Raven.js will report any uncaught exceptions triggered from your application. For advanced usage examples of Raven.js, please read :doc:`Raven.js usage <../usage>`.
We also do support native crashes via minidumps.

Installation
------------

Both packages are available via npm.
All packages are available via npm.

.. code-block:: sh

$ npm install raven raven-js --save
$ npm install @sentry/electron --save

Configuring the Client
----------------------
This will also install `@sentry/wizard`. Run the wizard the help you finish your setup:
With ``yarn`` you can just call:

First, let's configure ``main process``, which uses the Node.js SDK:
.. code-block:: sh

.. code-block:: javascript
$ yarn sentry-wizard --integration=electron

var Raven = require('raven');
If you only have ``npm`` call:

Raven.config('___PUBLIC_DSN___', {
captureUnhandledRejections: true
}).install();
.. code-block:: sh

And now ``renderer process``, which uses the Browser SDK:
$ node node_modules/.bin/sentry-wizard --integration=electron

.. code-block:: javascript
``sentry-wizard`` will display recommended packages like `electron-download` which we need
in order to symbolicate native crashes.
The wizard will also create a file called ``sentry.properties`` (which does contain
you account information) and ``sentry-symbols.js`` which helps you with the symbols
upload.

var Raven = require('raven-js');
Raven.config('___PUBLIC_DSN___').install();

window.addEventListener('unhandledrejection', function (event) {
Raven.captureException(event.reason);
});
Configuring the Client
----------------------

This configuration will also take care of unhandled Promise rejections, which can be handled in various ways. By default, Electron uses standard JS API.
To learn more about handling promises, refer to :ref:`raven-js-promises` documentation.
The following code should reside in the ``main process`` and ``renderer process``:

.. code-block:: javascript

Sending environment information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
const { SentryClient } = require('@sentry/electron');

SentryClient.create({
dsn: '___PRIVATE_DSN___',
// ...
});

It's often a good idea to send platform information along with a caught error.
Some things that we can easily add, but are not limited to, are:
This configuration will also take care of unhandled Promise rejections, which can be
handled in various ways. By default, Electron uses standard JS API.
To learn more about handling promises, refer to :ref:`raven-js-promises` documentation.

- Environment type (browser/renderer)
- Electron version
- Chrome version
- Operation System type
- Operation System release
Uploading symbols
~~~~~~~~~~~~~~~~~

You can configure both processes in the same way. To do this, require the standard Node.js module `os` and add a `tags` attribute to your `config` call:
The wizard should create a file called ``sentry-symbols.js`` which takes care of uploading
debug symbols to Sentry. Note that this is only necessary whenever you update your
version of electron. It usually takes quiet a while because it downloads debug symbols
of electron and uploads them to Sentry so we can symbolicate your native crashes.
You can always execute the script by calling:

.. code-block:: javascript
.. code-block:: sh

var os = require('os');
var Raven = require('raven');

Raven.config('___PUBLIC_DSN___', {
captureUnhandledRejections: true,
tags: {
process: process.type,
electron: process.versions.electron,
chrome: process.versions.chrome,
platform: os.platform(),
platform_release: os.release()
}
}).install();
$ node sentry-symbols.js