Aller au contenu principal

crashReporter

Soumet des rapports de plantage à un serveur distant.

Process: Main, Renderer

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' })

Pour configurer un serveur afin qu'il accepte et traite les rapports de plantage, vous pouvez utiliser les projets suivants :

[!NOTE] Electron uses Crashpad, not Breakpad, to collect and upload crashes, but for the time being, the upload protocol is the same.

Ou sinon vous pouvez utiliser une solution hébergée par un tiers :

Les rapports de plantage sont stockés temporairement avant d'être téléchargés dans un dossier du répertoire de données utilisateur de l'application, appelé 'Crashpad'. Vous pouvez modifier ce répertoire en appelant app.setPath('crashDumps', '/path/to/crashes') avant de démarrer le rapporteur de crash.

Electron utilise crashpad pour surveiller et signaler les plantages.

Méthodes​

Le module crashReporter dispose des méthodes suivantes :

crashReporter.start(options)​

  • 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 (facultatif) - Si la valeur est true, les plantages générés dans le processus principal ne seront pas transférés au gestionnaire de plantage du système. Par défaut la valeur est false.
    • rateLimit boolean (facultatif) macOS Windows - si la valeur est true, le nombre de plantages téléchargés sera limité à 1/heure. 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. 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.

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 127 bytes. Les clés dont les noms sont plus longs que le maximum seront ignorées sans d'avantage d'information. Key values longer than the maximum length will be truncated.

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

crashReporter.getLastCrashReport()​

Returns CrashReport | null - The date and ID of the last crash report. Seuls les rapports de bug qui ont été téléchargé seront renvoyés ; même si un rapport de plantages est présent sur le disque, il ne sera pas renvoyé avant qu'il soit téléchargé. Dans le cas où il n'y a pas de rapports téléchargés, cette méthode retourne null.

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

crashReporter.getUploadedReports()​

Returns CrashReport[]:

Retourne tous les rapports de bug téléchargés. Chaque rapport contient la date et l'ID téléchargé.

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

crashReporter.getUploadToServer()​

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)​

  • 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 127 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é.

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.

[!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. Les clés dont les noms sont plus longs que le maximum seront ignorées sans d'avantage d'information. Key values longer than the maximum length will be 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.

Dans les processus enfants node​

Étant donné que require('electron') n'est pas disponible dans les processus enfants de Node, les API suivantes sont disponibles sur l'objet process dans les processus enfants de Node.

process.crashReporter.start(options)​

See crashReporter.start().

Notez que si le rapporteur de plantage est démarré dans le processus principal, il surveillera automatiquement les processus fils, donc il ne devrait pas être démarré dans le processus fils. N'utilisez cette méthode que si le processus principal n'initialise pas le rapport de plantage .

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​

Le rapporteur de plantage enverra les données suivantes à submitURL comme un POST en multipart/form-data :

  • ver string - La version d'Electron.
  • platform string - Par exemple 'win32'.
  • process_type string - Par exemple 'renderer'.
  • 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.
  • upload_file_minidump File - Le rapport d'incident dans le format minidump.
  • Toutes les propriétés de niveau 1 de l'objet extra dans l'objet options de crashReporter.