fix: crashReporter incompatible with sandbox on Linux (#23265)
This commit is contained in:
Jeremy Apthorp
GitHub
parent
fc434f136b
commit
06bf0d08dc
77 changed files with 2235 additions and 2404 deletions
|
|
@ -610,6 +610,7 @@ Returns `String` - The current application directory.
|
|||
* `videos` Directory for a user's videos.
|
||||
* `logs` Directory for your app's log folder.
|
||||
* `pepperFlashSystemPlugin` Full path to the system version of the Pepper Flash plugin.
|
||||
* `crashDumps` Directory where crash dumps are stored.
|
||||
|
||||
Returns `String` - A path to a special directory or file associated with `name`. On
|
||||
failure, an `Error` is thrown.
|
||||
|
|
|
|||
|
|
@ -4,18 +4,13 @@
|
|||
|
||||
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
|
||||
|
||||
The following is an example of automatically submitting a crash report to a
|
||||
remote server:
|
||||
The following is an example of setting up Electron to automatically submit
|
||||
crash reports to a remote server:
|
||||
|
||||
```javascript
|
||||
const { crashReporter } = require('electron')
|
||||
|
||||
crashReporter.start({
|
||||
productName: 'YourName',
|
||||
companyName: 'YourCompany',
|
||||
submitURL: 'https://your-domain.com/url-to-submit',
|
||||
uploadToServer: true
|
||||
})
|
||||
crashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })
|
||||
```
|
||||
|
||||
For setting up a server to accept and process crash reports, you can use
|
||||
|
|
@ -30,11 +25,19 @@ Or use a 3rd party hosted solution:
|
|||
* [Sentry](https://docs.sentry.io/clients/electron)
|
||||
* [BugSplat](https://www.bugsplat.com/docs/platforms/electron)
|
||||
|
||||
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.
|
||||
Crash reports are stored temporarily before being uploaded in a directory
|
||||
underneath the app's user data directory (called 'Crashpad' on Windows and Mac,
|
||||
or 'Crash Reports' on Linux). You can override this directory by calling
|
||||
`app.setPath('crashDumps', '/path/to/crashes')` before starting the crash
|
||||
reporter.
|
||||
|
||||
On Windows and macOS, Electron uses
|
||||
[crashpad](https://chromium.googlesource.com/crashpad/crashpad/+/master/README.md)
|
||||
to monitor and report crashes. On Linux, Electron uses
|
||||
[breakpad](https://chromium.googlesource.com/breakpad/breakpad/+/master/). This
|
||||
is an implementation detail driven by Chromium, and it may change in future. In
|
||||
particular, crashpad is newer and will likely eventually replace breakpad on
|
||||
all platforms.
|
||||
|
||||
## Methods
|
||||
|
||||
|
|
@ -43,45 +46,68 @@ The `crashReporter` module has the following methods:
|
|||
### `crashReporter.start(options)`
|
||||
|
||||
* `options` Object
|
||||
* `companyName` String
|
||||
* `submitURL` String - URL that crash reports will be sent to as POST.
|
||||
* `productName` String (optional) - Defaults to `app.name`.
|
||||
* `uploadToServer` Boolean (optional) - Whether crash reports should be sent to the server. Default is `true`.
|
||||
* `ignoreSystemCrashHandler` Boolean (optional) - Default is `false`.
|
||||
* `companyName` String (optional) _Deprecated_ - Deprecated alias for
|
||||
`{ globalExtra: { _companyName: ... } }`.
|
||||
* `uploadToServer` Boolean (optional) - Whether crash reports should be sent
|
||||
to the server. If false, crash reports will be collected and stored in the
|
||||
crashes directory, but not uploaded. Default is `true`.
|
||||
* `ignoreSystemCrashHandler` Boolean (optional) - If true, crashes generated
|
||||
in the main process will not be forwarded to the system crash handler.
|
||||
Default is `false`.
|
||||
* `rateLimit` Boolean (optional) _macOS_ _Windows_ - If true, limit the
|
||||
number of crashes uploaded to 1/hour. Default is `false`.
|
||||
* `compress` Boolean (optional) _macOS_ _Windows_ - If true, crash reports
|
||||
will be compressed and uploaded with `Content-Encoding: gzip`. Not all
|
||||
collection servers support compressed payloads. Default is `false`.
|
||||
* `extra` Record<String, String> (optional) - An object you can define that will be sent along with the
|
||||
report. Only string properties are sent correctly. Nested objects are not
|
||||
supported. When using Windows, the property names and values must be fewer than 64 characters.
|
||||
* `crashesDirectory` String (optional) - Directory to store the crash reports temporarily (only used when the crash reporter is started via `process.crashReporter.start`).
|
||||
* `extra` Record<String, String> (optional) - Extra string key/value
|
||||
annotations that will be sent along with crash reports that are generated
|
||||
in the main process. Only string values are supported. Crashes generated in
|
||||
child processes will not contain these extra
|
||||
parameters to crash reports generated from child processes, call
|
||||
[`addExtraParameter`](#crashreporteraddextraparameterkey-value) from the
|
||||
child process.
|
||||
* `globalExtra` Record<String, String> (optional) - Extra string key/value
|
||||
annotations that will be sent along with any crash reports generated in any
|
||||
process. These annotations cannot be changed once the crash reporter has
|
||||
been started. If a key is present in both the global extra parameters and
|
||||
the process-specific extra parameters, then the global one will take
|
||||
precedence. By default, `productName` and the app version are included, as
|
||||
well as the Electron version.
|
||||
|
||||
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.
|
||||
You can pass different options to `crashReporter.start` when calling from different processes.
|
||||
This method must be called before using any other `crashReporter` APIs. Once
|
||||
initialized this way, the crashpad handler collects crashes from all
|
||||
subsequently created processes. The crash reporter cannot be disabled once
|
||||
started.
|
||||
|
||||
**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
|
||||
reports temporarily. You can test this out by calling `process.crash()` to crash the child process.
|
||||
This method should be called as early as possible in app startup, preferably
|
||||
before `app.on('ready')`. If the crash reporter is not initialized at the time
|
||||
a renderer process is created, then that renderer process will not be monitored
|
||||
by the crash reporter.
|
||||
|
||||
**Note:** If you need send additional/updated `extra` parameters after your
|
||||
first call `start` you can call `addExtraParameter` on macOS or call `start`
|
||||
again with the new/updated `extra` parameters on Linux and Windows.
|
||||
**Note:** You can test out the crash reporter by generating a crash using
|
||||
`process.crash()`.
|
||||
|
||||
**Note:** On macOS and windows, 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.
|
||||
**Note:** If you need to send additional/updated `extra` parameters after your
|
||||
first call `start` you can call `addExtraParameter`.
|
||||
|
||||
**Note:** Parameters passed in `extra`, `globalExtra` or set with
|
||||
`addExtraParameter` have limits on the length of the keys and values. Key names
|
||||
must be at most 39 bytes long, and values must be no longer than 127 bytes.
|
||||
Keys with names longer than the maximum will be silently ignored. Key values
|
||||
longer than the maximum length will be truncated.
|
||||
|
||||
**Note:** Calling this method from the renderer process is deprecated.
|
||||
|
||||
### `crashReporter.getLastCrashReport()`
|
||||
|
||||
Returns [`CrashReport`](structures/crash-report.md):
|
||||
Returns [`CrashReport`](structures/crash-report.md) - The date and ID of the
|
||||
last crash report. Only crash reports that have been uploaded will be returned;
|
||||
even if a crash report is present on disk it will not be returned until it is
|
||||
uploaded. In the case that there are no uploaded reports, `null` is returned.
|
||||
|
||||
Returns the date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. In the case that there are no uploaded reports, `null` is returned.
|
||||
**Note:** Calling this method from the renderer process is deprecated.
|
||||
|
||||
### `crashReporter.getUploadedReports()`
|
||||
|
||||
|
|
@ -90,43 +116,61 @@ Returns [`CrashReport[]`](structures/crash-report.md):
|
|||
Returns all uploaded crash reports. Each report contains the date and uploaded
|
||||
ID.
|
||||
|
||||
**Note:** Calling this method from the renderer process is deprecated.
|
||||
|
||||
### `crashReporter.getUploadToServer()`
|
||||
|
||||
Returns `Boolean` - Whether reports should be submitted to the server. Set through
|
||||
the `start` method or `setUploadToServer`.
|
||||
|
||||
**Note:** This API can only be called from the main process.
|
||||
**Note:** Calling this method from the renderer process is deprecated.
|
||||
|
||||
### `crashReporter.setUploadToServer(uploadToServer)`
|
||||
|
||||
* `uploadToServer` Boolean _macOS_ - Whether reports should be submitted to the server.
|
||||
* `uploadToServer` Boolean - Whether reports should be submitted to the server.
|
||||
|
||||
This would normally be controlled by user preferences. This has no effect if
|
||||
called before `start` is called.
|
||||
|
||||
**Note:** This API can only be called from the main process.
|
||||
**Note:** Calling this method from the renderer process is deprecated.
|
||||
|
||||
### `crashReporter.addExtraParameter(key, value)` _macOS_ _Windows_
|
||||
### `crashReporter.getCrashesDirectory()` _Deprecated_
|
||||
|
||||
* `key` String - Parameter key, must be less than 64 characters long.
|
||||
* `value` String - Parameter value, must be less than 64 characters long.
|
||||
Returns `String` - The directory where crashes are temporarily stored before being uploaded.
|
||||
|
||||
Set an extra parameter to be sent with the crash report. The values
|
||||
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 and windows, if you need to add/update extra parameters on Linux after your first call to `start` you can call `start` again with the updated `extra` options.
|
||||
**Note:** This method is deprecated, use `app.getPath('crashDumps')` instead.
|
||||
|
||||
### `crashReporter.removeExtraParameter(key)` _macOS_ _Windows_
|
||||
### `crashReporter.addExtraParameter(key, value)`
|
||||
|
||||
* `key` String - Parameter key, must be less than 64 characters long.
|
||||
* `key` String - Parameter key, must be no longer than 39 bytes.
|
||||
* `value` String - Parameter value, must be no longer than 127 bytes.
|
||||
|
||||
Remove a extra parameter from the current set of parameters so that it will not be sent with the crash report.
|
||||
Set an extra parameter to be sent with the crash report. The values specified
|
||||
here will be sent in addition to any values set via the `extra` option when
|
||||
`start` was called.
|
||||
|
||||
Parameters added in this fashion (or via the `extra` parameter to
|
||||
`crashReporter.start`) are specific to the calling process. Adding extra
|
||||
parameters in the main process will not cause those parameters to be sent along
|
||||
with crashes from renderer or other child processes. Similarly, adding extra
|
||||
parameters in a renderer process will not result in those parameters being sent
|
||||
with crashes that occur in other renderer processes or in the main process.
|
||||
|
||||
**Note:** Parameters have limits on the length of the keys and values. Key
|
||||
names must be no longer than 39 bytes, and values must be no longer than 127
|
||||
bytes. Keys with names longer than the maximum will be silently ignored. Key
|
||||
values longer than the maximum length will be truncated.
|
||||
|
||||
### `crashReporter.removeExtraParameter(key)`
|
||||
|
||||
* `key` String - Parameter key, must be no longer than 39 bytes.
|
||||
|
||||
Remove a extra parameter from the current set of parameters. Future crashes
|
||||
will not include this parameter.
|
||||
|
||||
### `crashReporter.getParameters()`
|
||||
|
||||
See all of the current parameters being passed to the crash reporter.
|
||||
|
||||
### `crashReporter.getCrashesDirectory()`
|
||||
|
||||
Returns `String` - The directory where crashes are temporarily stored before being uploaded.
|
||||
Returns `Record<String, String>` - The current 'extra' parameters of the crash reporter.
|
||||
|
||||
## Crash Report Payload
|
||||
|
||||
|
|
|
|||
|
|
@ -12,8 +12,73 @@ This document uses the following convention to categorize breaking changes:
|
|||
- **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
|
||||
- **Removed:** An API or feature was removed, and is no longer supported by Electron.
|
||||
|
||||
## Planned Breaking API Changes (12.0)
|
||||
|
||||
### Removed: `crashReporter` methods in the renderer process
|
||||
|
||||
The following `crashReporter` methods are no longer available in the renderer
|
||||
process:
|
||||
|
||||
- `crashReporter.start`
|
||||
- `crashReporter.getLastCrashReport`
|
||||
- `crashReporter.getUploadedReports`
|
||||
- `crashReporter.getUploadToServer`
|
||||
- `crashReporter.setUploadToServer`
|
||||
- `crashReporter.getCrashesDirectory`
|
||||
|
||||
They should be called only from the main process.
|
||||
|
||||
See [#23265](https://github.com/electron/electron/pull/23265) for more details.
|
||||
|
||||
## Planned Breaking API Changes (11.0)
|
||||
|
||||
## Planned Breaking API Changes (10.0)
|
||||
|
||||
### Deprecated: `companyName` argument to `crashReporter.start()`
|
||||
|
||||
The `companyName` argument to `crashReporter.start()`, which was previously
|
||||
required, is now optional, and further, is deprecated. To get the same
|
||||
behavior in a non-deprecated way, you can pass a `companyName` value in
|
||||
`globalExtra`.
|
||||
|
||||
```js
|
||||
// Deprecated in Electron 10
|
||||
crashReporter.start({ companyName: 'Umbrella Corporation' })
|
||||
// Replace with
|
||||
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })
|
||||
```
|
||||
|
||||
### Deprecated: `crashReporter.getCrashesDirectory()`
|
||||
|
||||
The `crashReporter.getCrashesDirectory` method has been deprecated. Usage
|
||||
should be replaced by `app.getPath('crashDumps')`.
|
||||
|
||||
```js
|
||||
// Deprecated in Electron 10
|
||||
crashReporter.getCrashesDirectory()
|
||||
// Replace with
|
||||
app.getPath('crashDumps')
|
||||
```
|
||||
|
||||
### Deprecated: `crashReporter` methods in the renderer process
|
||||
|
||||
Calling the following `crashReporter` methods from the renderer process is
|
||||
deprecated:
|
||||
|
||||
- `crashReporter.start`
|
||||
- `crashReporter.getLastCrashReport`
|
||||
- `crashReporter.getUploadedReports`
|
||||
- `crashReporter.getUploadToServer`
|
||||
- `crashReporter.setUploadToServer`
|
||||
- `crashReporter.getCrashesDirectory`
|
||||
|
||||
The only non-deprecated methods remaining in the `crashReporter` module in the
|
||||
renderer are `addExtraParameter`, `removeExtraParameter` and `getParameters`.
|
||||
|
||||
All above methods remain non-deprecated when called from the main process.
|
||||
|
||||
See [#23265](https://github.com/electron/electron/pull/23265) for more details.
|
||||
|
||||
### Removed: Browser Window Affinity
|
||||
|
||||
The `affinity` option when constructing a new `BrowserWindow` will be removed
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue