崩溃日志报告

将崩溃日志提交给远程服务器

进程: Main, Renderer

The following is an example of setting up Electron to automatically submit crash reports to a remote server:

  1. const { crashReporter } = require('electron')
  2. crashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })

构建一个用于接受和处理崩溃日志的服务,你需要以下工程

或者使用第三方托管的解决办法:

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 to monitor and report crashes. On Linux, Electron uses breakpad. 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.

方法

crashReporter 模块具有以下方法:

crashReporter.start(options)

  • 选项 对象
    • submitURL 字符串 - 崩溃日志将以POST的方式发送给此URL.
    • productName String (optional) - Defaults to app.name.
    • 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. 默认值为 true
    • ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. 默认值为 false.
    • rateLimit Boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. 默认值为 false.
    • compress Boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. 默认值为 false.
    • 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 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.

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.

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: 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. 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 - 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. 如果没有上传的报告,则返回null

Note: Calling this method from the renderer process is deprecated.

crashReporter.getUploadedReports()

返回 CrashReport[]:

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: Calling this method from the renderer process is deprecated.

crashReporter.setUploadToServer(uploadToServer)

  • 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: Calling this method from the renderer process is deprecated.

crashReporter.getCrashesDirectory() Deprecated

Returns String - The directory where crashes are temporarily stored before being uploaded.

Note: This method is deprecated, use app.getPath('crashDumps') instead.

crashReporter.addExtraParameter(key, value)

  • key String - Parameter key, must be no longer than 39 bytes.
  • value String - Parameter value, must be no longer than 127 bytes.

设置一个在发送崩溃报告时将额外包含的参数。 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 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.

Note: On linux values that are longer than 127 bytes will be chunked into multiple keys, each 127 bytes in length. E.g. addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. On your crash reporting backend you should stitch together keys in this format.

crashReporter.removeExtraParameter(key)

  • key String - Parameter key, must be no longer than 39 bytes.

Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.

crashReporter.getParameters()

Returns Record<String, String> - The current ‘extra’ parameters of the crash reporter.

崩溃报告内容

崩溃报告将发送下面 multipart/form-data POST 型的数据给 submitURL:

  • ver String - Electron 的版本.
  • platform String - 例如 ‘win32’.
  • process_type String - 例如 ‘renderer’.
  • guid String - 例如 ‘5e1286fc-da97-479e-918b-6bfb0c3d1c72’.
  • _version String - package.json 里的版本号.
  • _productName String - crashReporter options 对象中的产品名字
  • prod String - Name of the underlying product. In this case Electron.
  • _companyName String - crashReporter options 对象中的公司名称
  • upload_file_minidump File - minidump 格式的崩溃报告
  • All level one properties of the extra object in the crashReporter options object.