electron/docs/api/crash-reporter.md

158 lines
6.5 KiB
Markdown
Raw Normal View History

2015-08-27 15:11:51 +00:00
# crashReporter
2013-08-14 22:43:35 +00:00
2016-04-21 22:39:12 +00:00
> Submit crash reports to a remote server.
2015-08-25 12:01:57 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
2016-11-03 17:26:00 +00:00
2015-08-25 12:16:20 +00:00
The following is an example of automatically submitting a crash report to a
remote server:
2013-08-14 22:43:35 +00:00
```javascript
const {crashReporter} = require('electron')
2015-08-28 17:50:30 +00:00
2013-11-14 05:39:44 +00:00
crashReporter.start({
productName: 'YourName',
companyName: 'YourCompany',
2015-11-13 08:03:40 +00:00
submitURL: 'https://your-domain.com/url-to-submit',
uploadToServer: true
})
2013-08-14 22:43:35 +00:00
```
For setting up a server to accept and process crash reports, you can use
following projects:
* [socorro](https://github.com/mozilla/socorro)
2016-05-06 17:09:24 +00:00
* [mini-breakpad-server](https://github.com/electron/mini-breakpad-server)
2016-10-05 21:10:45 +00:00
Crash reports are saved locally in an application-specific temp directory folder.
For a `productName` of `YourName`, crash reports will be stored in a folder
named `YourName Crashes` inside the temp directory. You can customize this temp
directory location for your app by calling the `app.setPath('temp', '/my/custom/temp')`
API before starting the crash reporter.
2015-08-25 12:01:57 +00:00
## Methods
2016-11-21 23:42:24 +00:00
The `crashReporter` module has the following methods:
2015-08-25 12:01:57 +00:00
### `crashReporter.start(options)`
* `options` Object
2016-10-30 10:46:20 +00:00
* `companyName` String (optional)
* `submitURL` String - URL that crash reports will be sent to as POST.
2016-09-08 18:52:21 +00:00
* `productName` String (optional) - Defaults to `app.getName()`.
* `uploadToServer` Boolean (optional) - Whether crash reports should be sent to the server
Default is `true`.
2016-10-30 10:46:20 +00:00
* `ignoreSystemCrashHandler` Boolean (optional) - Default is `false`.
* `extra` Object (optional) - An object you can define that will be sent along with the
2017-02-02 21:01:49 +00:00
report. Only string properties are sent correctly. Nested objects are not
2017-06-26 15:35:57 +00:00
supported and the property names and values must be less than 64 characters long.
2017-09-08 03:21:35 +00:00
* `crashesDirectory` String (optional) - Directory to store the crashreports temporarily (only used when the crash reporter is started via `process.crashReporter.start`)
2016-11-28 23:37:06 +00:00
You are required to call this method before using any other `crashReporter` APIs
and in each process (main/renderer) from which you want to collect crash reports.
2016-11-28 23:37:06 +00:00
You can pass different options to `crashReporter.start` when calling from different processes.
2017-02-02 21:01:49 +00:00
**Note** Child processes created via the `child_process` module will not have access to the Electron modules.
Therefore, to collect crash reports from them, use `process.crashReporter.start` instead. Pass the same options as above
along with an additional one called `crashesDirectory` that should point to a directory to store the crash
2017-01-24 22:04:56 +00:00
reports temporarily. You can test this out by calling `process.crash()` to crash the child process.
**Note:** To collect crash reports from child process in Windows, you need to add this extra code as well.
2017-01-24 22:07:00 +00:00
This will start the process that will monitor and send the crash reports. Replace `submitURL`, `productName`
and `crashesDirectory` with appropriate values.
2017-01-24 22:03:54 +00:00
2017-02-09 20:47:02 +00:00
**Note:** If you need send additional/updated `extra` parameters after your
first call `start` you can call `setExtraParameter` on macOS or call `start`
again with the new/updated `extra` parameters on Linux and Windows.
2017-01-24 22:03:54 +00:00
```js
const args = [
2017-01-24 22:08:10 +00:00
`--reporter-url=${submitURL}`,
`--application-name=${productName}`,
`--crashes-directory=${crashesDirectory}`
]
const env = {
ELECTRON_INTERNAL_CRASH_SERVICE: 1
}
spawn(process.execPath, args, {
env: env,
detached: true
})
```
**Note:** On macOS, Electron uses a new `crashpad` client for crash collection and reporting.
If you want to enable crash reporting, initializing `crashpad` from the main process using `crashReporter.start` is required
regardless of which process you want to collect crashes from. Once initialized this way, the crashpad handler collects
crashes from all processes. You still have to call `crashReporter.start` from the renderer or child process, otherwise crashes from
them will get reported without `companyName`, `productName` or any of the `extra` information.
2015-05-30 02:03:59 +00:00
2015-08-25 12:01:57 +00:00
### `crashReporter.getLastCrashReport()`
2014-11-11 12:20:36 +00:00
Returns [`CrashReport`](structures/crash-report.md):
Returns the date and ID of the last crash report. If no crash reports have been
sent or the crash reporter has not been started, `null` is returned.
2014-11-11 12:20:36 +00:00
2015-08-25 12:01:57 +00:00
### `crashReporter.getUploadedReports()`
2015-06-05 11:05:55 +00:00
Returns [`CrashReport[]`](structures/crash-report.md):
2015-08-26 23:28:44 +00:00
Returns all uploaded crash reports. Each report contains the date and uploaded
ID.
2015-06-05 11:05:55 +00:00
### `crashReporter.getUploadToServer()` _Linux_ _macOS_
2016-11-08 00:12:46 +00:00
Returns `Boolean` - Whether reports should be submitted to the server. Set through
2016-11-22 08:30:20 +00:00
the `start` method or `setUploadToServer`.
2016-11-08 00:12:46 +00:00
2016-11-28 23:03:38 +00:00
**Note:** This API can only be called from the main process.
### `crashReporter.setUploadToServer(uploadToServer)` _Linux_ _macOS_
2016-11-08 00:03:57 +00:00
2016-11-22 08:30:20 +00:00
* `uploadToServer` Boolean _macOS_ - Whether reports should be submitted to the server
2016-11-08 00:03:57 +00:00
This would normally be controlled by user preferences. This has no effect if
called before `start` is called.
2016-11-08 00:03:57 +00:00
2016-11-28 23:03:38 +00:00
**Note:** This API can only be called from the main process.
2017-02-09 20:47:02 +00:00
### `crashReporter.setExtraParameter(key, value)` _macOS_
2017-06-26 15:35:57 +00:00
* `key` String - Parameter key, must be less than 64 characters long.
* `value` String - Parameter value, must be less than 64 characters long.
2017-02-09 20:47:02 +00:00
2017-06-27 17:40:14 +00:00
Set an extra parameter to be sent with the crash report. The values
2017-02-13 18:48:04 +00:00
specified here will be sent in addition to any values set via the `extra` option
when `start` was called. This API is only available on macOS, if you need to
add/update extra parameters on Linux and Windows after your first call to
`start` you can call `start` again with the updated `extra` options.
2017-02-09 20:47:02 +00:00
### `crashReporter.removeExtraParameter(key)` _macOS_
* `key` String - Parameter key, must be less than 64 characters long.
Remove a extra parameter from the current set of parameters so that it will not be sent with the crash report.
### `crashReporter.getParameters()`
See all of the current parameters being passed to the crash reporter.
2016-11-21 23:42:24 +00:00
## Crash Report Payload
The crash reporter will send the following data to the `submitURL` as
a `multipart/form-data` `POST`:
2015-08-25 12:18:02 +00:00
* `ver` String - The version of Electron.
* `platform` String - e.g. 'win32'.
* `process_type` String - e.g. 'renderer'.
* `guid` String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'
2015-08-25 12:18:02 +00:00
* `_version` String - The version in `package.json`.
2015-08-25 12:16:20 +00:00
* `_productName` String - The product name in the `crashReporter` `options`
2015-08-25 12:18:02 +00:00
object.
* `prod` String - Name of the underlying product. In this case Electron.
2015-08-25 12:16:20 +00:00
* `_companyName` String - The company name in the `crashReporter` `options`
2015-08-25 12:18:02 +00:00
object.
* `upload_file_minidump` File - The crash report in the format of `minidump`.
2016-10-10 14:31:05 +00:00
* All level one properties of the `extra` object in the `crashReporter`
`options` object.