メインコンテンツへ飛ぶ

crashReporter

クラッシュレポートをリモートサーバーに送信します。

プロセス: メイン, レンダラー

[!IMPORTANT] コンテキスト分離を有効にしてレンダラープロセスからこの API を呼び出す場合は、プリロードスクリプトに API 呼び出しを記述し、contextBridge API でその API 呼び出しを 公開 します。

以下は、Electron が外部サーバーにクラッシュレポートを自動送信するように設定する例です。

const { crashReporter } = require('electron')

crashReporter.start({ submitURL: 'https://your-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.

メソッド​

crashReporter モジュールには以下のメソッドがあります。

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.

  • options Object
    • submitURL string (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.
    • productName string (任意) - 省略値は、app.name です。
    • companyName string (任意) 非推奨 - { globalExtra: { _companyName: ... } } の非推奨な別名です。
    • uploadToServer boolean (任意) - クラッシュレポートをサーバーに送信するかどうか。 false の場合、クラッシュレポートは収集されてクラッシュのディレクトリに保存されますが、アップロードされません。省略値は 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. 省略値は 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. 省略値は false です。
    • compress boolean (任意) - true の場合、クラッシュレポートは圧縮され Content-Encoding: gzip でアップロードされます。 Setting this to false while uploadToServer is true is deprecated and logs a deprecation warning. 省略値は true です。
    • extra Record<string, string> (任意) - メインプロセスが生成するクラッシュレポートと一緒に送信される、追加のキー/バリューアノテーションの文字列。文字列のみをサポートしています。子プロセスで生成されたクラッシュには、これらの追加パラメータは含まれません。子プロセスから生成されたクラッシュレポートに追加のパラメータを付加するには、子プロセスから addExtraParameter を呼ぶ必要があります。
    • globalExtra Record<string, string> (任意) - 任意のプロセスが生成したクラッシュレポートと一緒に送信される、追加のキー/バリューアノテーションの文字列。これらのアノテーションは、クラッシュレポーターを起動すると変更できません。グローバル追加パラメータとプロセス固有の追加パラメータの両方に同じキーが存在する場合、グローバルのものが優先されます。デフォルトでは、 productName と、Electron のバージョンと同様のアプリのバージョンが含まれています。 Global extra parameters are not returned by getParameters().

このメソッドは、他の crashReporter API を使用する前に呼ばれなければなりません。このように初期化すると、crashpad ハンドラは、以降作成されたすべてのプロセスからクラッシュを収集します。一度起動したクラッシュリポーターは無効にできません。

このメソッドは、アプリの起動時にできるだけ早く、できれば app.on('ready') の前に呼び出す必要があります。レンダラープロセスの作成時にクラッシュリポーターが初期化されていない場合、そのレンダラープロセスはクラッシュリポーターに監視されません。

注釈

process.crash() でクラッシュさせることで、crashReporter をテストできます。

[!NOTE] 最初の start 呼び出しの後に追加、または更新された extra パラメータを 送信する必要がある場合は、addExtraParameter を呼び出すことにより可能です。

注釈

extra、globalExtra で渡すパラメータや addExtraParameter で設定するパラメータは、キーと値の長さに制限があります。 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] このメソッドはメインプロセスからのみ利用できます。

crashReporter.getLastCrashReport()​

History

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] このメソッドはメインプロセスからのみ利用できます。

crashReporter.getUploadedReports()​

History

戻り値 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] このメソッドはメインプロセスからのみ利用できます。

crashReporter.getUploadToServer()​

History

戻り値 boolean - リポートがサーバに送信されるべきかどうか。 start メソッドまたは setUploadToServer を通して設定されます。

[!NOTE] このメソッドはメインプロセスからのみ利用できます。

crashReporter.setUploadToServer(uploadToServer)​

History
  • uploadToServer boolean - レポートがサーバーに送信されるかどうか.

これは通常、ユーザーの設定によって制御されます。これは start が呼ばれるまでは何もしません。

[!NOTE] このメソッドはメインプロセスからのみ利用できます。

crashReporter.addExtraParameter(key, value)​

  • key string - パラメータキー。39 バイト未満でなければなりません。
  • value string - パラメータの値。20320 バイト未満でなければなりません。

クラッシュリポートで送信される追加のパラメータを設定します。ここで指定された値は、start が呼ばれたときに extra オプションで設定された値に加えて送信されます。 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.

この方法 (または crashReporter.start のextra パラメータ) で追加されたパラメータは、呼び出すプロセスに固有のものです。メインプロセスでパラメータを追加しても、そのパラメータはレンダラーや他の子プロセスからのクラッシュと一緒には送信されません。同様に、レンダラープロセスでパラメータを追加しても、他のレンダラープロセスやメインプロセスで発生するクラッシュでそれらのパラメータは送信されません。 Processes created with utilityProcess have no API for setting extra parameters, so only globalExtra values are sent with their crashes.

[!NOTE] パラメータはキーと値の長さに制限があります。キー名の長さは 39 バイト以下、値の長さは 20320 バイト以下でなければなりません。 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 - パラメータキー。39 バイト未満でなければなりません。

現在のパラメータセットから追加のパラメータを削除します。以降のクラッシュにこのパラメータは含まれなくなります。

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.

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

crashReporter.getParameters() をご覧ください。

process.crashReporter.addExtraParameter(key, value)​

crashReporter.addExtraParameter(key, value) をご覧ください。

process.crashReporter.removeExtraParameter(key)​

crashReporter.removeExtraParameter(key) をご覧ください。

クラッシュリポートのペイロード​

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 - Electronのバージョン。
  • platform string - 例えば、'win32'。
  • process_type string - e.g. 'renderer', or 'browser' for the main process.
  • guid string - 例えば、'5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
  • _version string - package.json のバージョン。
  • _productName string - crashReporter の options のプロダクト名。
  • prod string - 基底にあるプロダクトの名前。この場合は Electron です。
  • _companyName string - crashReporter の options の会社名。 Only sent if the deprecated companyName option is set.
  • upload_file_minidump File - minidumpフォーマットのクラッシュレポート。
  • crashReporterのoptions内のglobalExtraオブジェクトの全ての最上位プロパティ。
  • 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().