crashReporter

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

Process: Main, Renderer

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

const { crashReporter } = require('electron')

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

クラッシュレポートを受信して処理するサーバーをセットアップするには、以下のプロジェクトを使用することができます。

• socorro
• mini-breakpad-server

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

また、サードパーティによる解決方法も使用できます。

• Backtrace
• Sentry
• BugSplat
• Bugsnag

クラッシュリポートは、アップロードされる前にアプリのユーザーデータディレクトリ下にある「Crashpad」というディレクトリに一時保存されます。 クラッシュリポーターを起動する前に app.setPath('crashDumps', '/path/to/crashes') を呼び出すことで、このディレクトリをオーバーライドできます。

Electron は crashpad を使用してクラッシュを監視し報告します。

メソッド

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

crashReporter.start(options)

• 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 (任意) - true の場合、メインプロセスで発生したクラッシュをシステムクラッシュハンドラに転送しません。 省略値は false です。
  • rateLimit boolean (任意) macOS Windows - true の場合、アップロードされるクラッシュの数を 1 時間につき 1 つに制限します。 省略値は false です。
  • compress boolean (任意) - true の場合、クラッシュレポートは圧縮され Content-Encoding: gzip でアップロードされます。 省略値は true です。
  • extra Record<string, string> (任意) - メインプロセスが生成するクラッシュレポートと一緒に送信される、追加のキー/バリューアノテーションの文字列。 文字列のみをサポートしています。 子プロセスから生成されたクラッシュレポートはこれらの追加パラメータを含みません。子プロセスが生成したクラッシュにこれらを含める場合は、子プロセスから addExtraParameter を呼び出してください。
  • globalExtra Record<string, string> (任意) - 任意のプロセスが生成したクラッシュレポートと一緒に送信される、追加のキー/バリューアノテーションの文字列。 これらのアノテーションは、クラッシュレポーターを起動すると変更できません。 グローバル追加パラメータとプロセス固有の追加パラメータの両方に同じキーが存在する場合、グローバルのものが優先されます。 デフォルトでは、 productName と、Electron のバージョンと同様のアプリのバージョンが含まれています。

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

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

[!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. 最大値より長い名前を持つキーは警告を出さずに無視されます。 Key values longer than the maximum length will be truncated.

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

crashReporter.getLastCrashReport()

戻り値 CrashReport | null - 最後のクラッシュリポートの日付と ID。 アップロードされたクラッシュリポートだけを返します。例えば、クラッシュリポートがディスク上に存在したとしても、アップロードしていなければそれを返しません。 アップロードされたリポートがない場合、これは null を返します。

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

crashReporter.getUploadedReports()

Returns CrashReport[]:

アップロードされたすべてのクラッシュリポートを返します。 各リポートには、日付とアップロードされた ID が含まれています。

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

crashReporter.getUploadToServer()

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

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

crashReporter.setUploadToServer(uploadToServer)

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

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

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

crashReporter.addExtraParameter(key, value)

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

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

この方法 (または crashReporter.start のextra パラメータ) で追加されたパラメータは、呼び出すプロセスに固有のものです。 メインプロセスでパラメータを追加しても、そのパラメータはレンダラーや他の子プロセスからのクラッシュと一緒には送信されません。 同様に、レンダラープロセスでパラメータを追加しても、他のレンダラープロセスやメインプロセスで発生するクラッシュでそれらのパラメータは送信されません。

[!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. 最大値より長い名前を持つキーは警告を出さずに無視されます。 Key values longer than the maximum length will be truncated.

crashReporter.removeExtraParameter(key)

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

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

crashReporter.getParameters()

Returns Record<string, string> - The current 'extra' parameters of the crash reporter.

Node の子プロセスで

Node の子プロセスでは require('electron') は利用できないので、Node の子プロセスの process オブジェクトでは以下の API が利用できます。

process.crashReporter.start(options)

See crashReporter.start().

注意として、メインプロセスで起動したクラッシュリポーターは自動的に子プロセスを監視するので、その場合に子プロセスでは起動しないでください。 この方法は、メインプロセスがクラッシュリポーターを初期化しない場合にのみ使用してください。

process.crashReporter.getParameters()

See crashReporter.getParameters().

process.crashReporter.addExtraParameter(key, value)

See crashReporter.addExtraParameter(key, value).

process.crashReporter.removeExtraParameter(key)

See crashReporter.removeExtraParameter(key).

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

クラッシュリポーターは、以下のデータを submitURL に multipart/form-data の POST で送信します。

• 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 - 基底にあるプロダクトの名前。 この場合は Electron です。
• _companyName string - crashReporter の options の会社名。
• upload_file_minidump File - minidumpフォーマットのクラッシュレポート。
• crashReporterのoptions内のextraオブジェクトの全ての最上位プロパティ。