Aller au contenu principal

crashReporter

Soumet des rapports de plantage à un serveur distant.

Processus : 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 utilise Crashpad et non Breakpad pour collecter et enregistrer les crashs, mais pour le moment le protocole d'upload est le même .

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> (facultatif) - Annotations supplémentaires de type clé/valeur en string qui seront envoyées avec les rapports de crash générés dans le processus principal. Seuls les variables de type string sont pris en charge. Les crash intervenant dans des processus enfants ne contiendront pas ces paramètres et dans ce cas il faut faire appel à addExtraParameter à partir du processus enfant.
    • globalExtra Records<string, string> (facultatif) - Annotations supplémentaires sous forme de clé/valeur de type string envoyées avec les rapports de crash générés dans le processus principal. 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: Vous pouvez tester le reporter de crash en produisant un crash généré par process.crash().

Note : si vous devez envoyer des paramètres extra supplémentaires/ou mis à jour après votre premier appel start vous pouvez appeler l addExtraParameter.

Note : Les paramètres passés dans extra, globalExtra ou fixés par addExtraParameter sont limités en longueur pour leurs clés et valeurs. Les noms de clés ne doivent pas dépasser 39 bytes de long, et les valeurs ne doivent pas dépasser 127 bytes . Les clés dont les noms sont plus longs que le maximum seront ignorées sans d'avantage d'information. Les valeurs elles, seront tronquées à la valeur maximale.

Note : Cette méthode n'est disponible que dans le processus principal.

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 : Cette méthode n'est disponible que dans le processus principal.

crashReporter.getUploadedReports()

Retourne CrashReport[] :

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

Note : Cette méthode n'est disponible que dans le processus principal.

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 : Cette méthode n'est disponible que dans le processus principal.

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 : Cette méthode n'est disponible que dans le processus principal.

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 : Les paramètres ont des limites sur la longueur des clés et des valeurs. Les noms des clés ne doivent pas être plus longs que 39 bytes, et les valeurs ne doivent pas être plus longues que 20320 octets. Les clés dont les noms sont plus longs que le maximum seront ignorées sans d'avantage d'information. Les valeurs de la clé plus longues que la longueur maximale seront tronquées.

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

Retourne Record<string, string> - Paramètres 'extra' actuels du rapport de plantage.

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)

Voir 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()

Voir crashReporter.getParameters().

process.crashReporter.addExtraParameter(key, value)

Voir crashReporter.addExtraParameter(key, value).

process.crashReporter.removeExtraParameter(key)

Voir 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.