crashReporter

Soumet des rapports de plantage à un serveur distant.

Processus: Main, Renderer

[!IMPORTANT] Si vous voulez appeler cette API à partir d'un processus de rendu avec l'isolation du contexte activée, placez l'appel API dans votre script de préchargement et exposez-le en utilisant l'API contextBridge.

L'exemple suivant montre comment configurer Electron pour qu'il envoie automatiquement des rapports de plantage à un serveur distant :

const { crashReporter } = require('electron')

crashReporter.start({ submitURL: 'https://votre-domain.com/url-to-submit' })

For a guide to collecting, receiving and symbolicating crash reports, including how to run your own crash server or use a hosted service, see the Crash Reporting tutorial.

Electron uses Crashpad to monitor and report crashes. Crashpad uses the same upload protocol as Breakpad, so servers that accept Breakpad minidumps can receive Electron's crash reports.

Crash reports are stored under the directory returned by app.getPath('crashDumps'). You can override it by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter. The layout of files inside this directory is an implementation detail and may change between versions of Electron.

The crashReporter module is disabled in Mac App Store builds. Its methods can be called, but they do nothing: no crash reports are collected or uploaded, getUploadedReports() returns an empty array and getUploadToServer() returns false.

On Windows, some crashes never reach an in-process crash handler, most notably __fastfail terminations (STATUS_STACK_BUFFER_OVERRUN, raised by security-check failures, Control Flow Guard violations and the C runtime's abort()). To capture these, Electron ships electron_wer.dll, a Windows Error Reporting (WER) runtime exception helper that Windows (10 20H1 and later) loads out-of-process after such a crash and that asks the crashpad handler to write a minidump. When crashReporter.start() is called, Electron lists the DLL under HKEY_CURRENT_USER\Software\Microsoft\Windows\Windows Error Reporting\RuntimeExceptionHelperModules, which Windows requires before it will load a helper, and registers it for every Electron process. The helper is looked up as <executable name>_wer.dll next to the executable, so if you rename electron.exe to myapp.exe when packaging, rename electron_wer.dll to myapp_wer.dll as well. Installers that write to HKEY_LOCAL_MACHINE may list it there instead. To opt out, do not ship the DLL.

Méthodes

Le module crashReporter dispose des méthodes suivantes :

crashReporter.start(options)

History

Version(s)	Changes
None	Added rateLimit and compress options.
None	Deprecated calling this method in the renderer process.
None	Default value of compress option changed from false to true.
None	The submitURL parameter is now optional when uploadToServer is false.

• Objet options
  • submitURL string (facultatif) - URL à laquelle les rapports de plantage seront envoyés sous la forme de POST. Requis sauf si uploadToServer est false.
  • productName string (facultatif) - app.name.
  • companyName string (facultatif) Déprécié - Alias obsolète pour { globalExtra: { _companyName: ... } }.
  • uploadToServer boolean (facultatif) - Indique si les rapports de crash doivent être envoyés au serveur. Si la valeur est false, les rapports de plantage seront collectés et stockés dans le répertoire de crash mais pas téléchargés. La valeur par défaut est true.
  • ignoreSystemCrashHandler boolean (optional) macOS Linux - If true, crashes generated in the main process will not be forwarded to the system crash handler. This option has no effect on Windows. Par défaut la valeur est false.
  • rateLimit boolean (optional) - If true, limit the number of crashes uploaded to 1/hour. Crash reports over the limit are not uploaded, but are still stored on disk. Par défaut la valeur est false.
  • compress boolean (facultatif) - Si la valeur est true, les rapports de creash seront compressés et téléchargés avec Content-Encoding: gzip. Setting this to false while uploadToServer is true is deprecated and logs a deprecation warning. La valeur par défaut est true.
  • 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. Seuls les variables de type string sont pris en charge. Crashes generated in child processes will not include these extra parameters. To add extra parameters to crash reports generated from child processes, call addExtraParameter 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. Ces annotations ne peuvent pas être modifiées une fois que le crashreporter a été démarré. Si une clé est présente à la fois dans les paramètres supplémentaires globaux et dans les paramètres supplémentaires spécifiques au processus, alors la clé globale prendra la priorité. Par défaut, productName et la version de l'application sont incluses, comme la version d'Electron. Global extra parameters are not returned by getParameters().

Cette méthode doit être appelée avant toute autre API de crashReporter. Une fois initialisé de cette façon, le gestionnaire de crash collectera les crash de tous les processus créés par la suite. Le rapporteur de crash ne peut pas être désactivé une fois démarré.

Cette méthode doit être appelée le plus tôt possible lors du démarrage de l'application et de préférence avant app.on('ready'). Si le rapporteur de plantage n'est pas encore initialisé au moment où un processus de rendu est créé, alors celui-ci ne sera pas surveillé en cas de crash.

[!NOTE] You can test out the crash reporter by generating a crash using process.crash().

[!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 20320 bytes. Keys with names longer than the maximum are ignored, and a warning is emitted. Values longer than the maximum length are truncated.

[!NOTE] This method is only available in the main process.

crashReporter.getLastCrashReport()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

Returns CrashReport | null - The date and ID of the crash report with the most recent upload time, from the list returned by getUploadedReports(). If there are no crash reports at all, null is returned.

If no report has been uploaded yet but some are stored on disk, a report that has not been uploaded may be returned. Check that its id is not empty before treating it as uploaded.

[!NOTE] This method is only available in the main process.

crashReporter.getUploadedReports()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

Returns CrashReport[]:

Returns the crash reports stored on disk. Each report contains the date it was uploaded and the ID that the crash server returned for it.

Despite the method's name, reports that have not been uploaded (for example because uploadToServer is false, the upload failed, or the report was rate limited) are included too. For those reports, id is an empty string and date is not meaningful. To list only uploaded reports, filter out reports with an empty id.

[!NOTE] This method is only available in the main process.

crashReporter.getUploadToServer()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

Retourne boolean - Indique si les rapports doivent être transmis au serveur. Ce qui est défini via la méthode start ou setUploadToServer.

[!NOTE] This method is only available in the main process.

crashReporter.setUploadToServer(uploadToServer)

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

• uploadToServer boolean - Indique si les rapports doivent être soumis au serveur.

Cela devrait normalement être contrôlé par les préférences de l’utilisateur. Cela n'a aucun effet si start est appelé avant.

[!NOTE] This method is only available in the main process.

crashReporter.addExtraParameter(key, value)

• key string - Clé du paramètre, ne devant pas dépasser 39 bytes.
• value string - Valeur du paramètre, ne devant pas dépasser 20320 bytes.

Définit un paramètre supplémentaire à envoyer avec le rapport de plantage. Les valeurs spécifiées ici seront envoyées en plus de toutes les valeurs définies via l'option extra lorsque start a été appelé. Calling this again with the same key replaces the value. The value is read when a crash happens, so you can update it as your app's state changes.

Les paramètres ajoutés de cette manière (ou via le paramètre extra à crashReporter.start) sont spécifiques au processus appelant. L'ajout de paramètres supplémentaires dans le processus principal n'entraînera pas l'envoi de ces paramètres lors de plantages du moteur de rendu ou d'autres processus enfants. De même, l'ajout de paramètres supplémentaires dans un processus de rendu ne conduira pas à l'envoi de ces paramètres lors de plantages qui se produisent dans d'autres processus de rendu ou dans le processus principal. Processes created with utilityProcess have no API for setting extra parameters, so only globalExtra values are sent with their crashes.

[!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 20320 bytes. Keys with names longer than the maximum are ignored, and a warning is emitted. Values longer than the maximum length are truncated.

crashReporter.removeExtraParameter(key)

• key string - Clé du paramètre, ne devant pas dépasser 39 bytes.

Supprime un paramètre supplémentaire de l'ensemble des paramètres courants. Les futurs crash n'incluront pas ce paramètre.

crashReporter.getParameters()

Returns Record<string, string> - The current 'extra' parameters of the crash reporter in the calling process, as set with the extra option and addExtraParameter. Parameters set with the globalExtra option are not included.

Dans les processus enfants node

Since require('electron') is not available in Node child processes (processes run with ELECTRON_RUN_AS_NODE, such as those created with child_process.fork()), the following APIs are available on the process object in Node child processes.

If the crash reporter is started in the main process, Node child processes are monitored automatically. There is no way to start the crash reporter from a Node child process.

process.crashReporter.getParameters()

See crashReporter.getParameters().

process.crashReporter.addExtraParameter(key, value)

See crashReporter.addExtraParameter(key, value).

process.crashReporter.removeExtraParameter(key)

See crashReporter.removeExtraParameter(key).

Payload du Crash Report

The crash reporter will send the following data to the submitURL as a multipart/form-data POST. Unless compress is false, the request body is gzip-compressed and sent with Content-Encoding: gzip.

• ver string - La version d'Electron.
• platform string - Par exemple 'win32'.
• process_type string - e.g. 'renderer', or 'browser' for the main process.
• guid string - Par exemple '5e1286fc-da97-479e-918b-6bfb0c3d1c72'.
• _version string - La version dans package.json.
• _productName string - Le nom du produit dans l'objet options de crashReporter.
• prod string - Nom du produit sous-jacent. Dans ce cas, Electron.
• _companyName string - Le nom de l'entreprise dans l'objet options de crashReporter. Only sent if the deprecated companyName option is set.
• upload_file_minidump File - Le rapport d'incident dans le format minidump.
• Toutes les propriétés de niveau 1 de l'objet globalExtra dans l'objet options de crashReporter.
• All extra parameters of the process that crashed, set with the extra option (main process only) or addExtraParameter.

Crashpad and Chromium may add other fields to the upload. These are not part of Electron's API and can change without notice, so don't rely on them.

The body of the server's response is stored as the crash report's ID, and is returned in the id field by getUploadedReports().