メインコンテンツへ飛ぶ

crashReporter

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

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

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

const { crashReporter } = require('electron')

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

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

注意: Electron はクラッシュの収集とアップロードに Breakpad ではなく Crashpad を使用していますが、当面は アップロードのプロトコルは同じです

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

クラッシュリポートは、アップロードされる前にアプリのユーザーデータディレクトリ下にある「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') の前に呼び出す必要があります。 レンダラープロセスの作成時にクラッシュリポーターが初期化されていない場合、そのレンダラープロセスはクラッシュリポーターに監視されません。

注: process.crash() でクラッシュを生成することで、クラッシュリポーターをテストできます。

注意: 最初の start 呼び出しの後に追加/更新された extra パラメータを送信する必要がある場合は、addExtraParameter を呼び出すことでできます。

注: extraglobalExtra で渡すパラメータや addExtraParameter で設定するパラメータは、キーと値の長さに制限があります。 キー名の長さは最大 39 バイト、値の長さは 127 バイト以下でなければなりません。 最大値より長い名前を持つキーは警告を出さずに無視されます。 キーの値が最大長より長ければ切り捨てられます。

注意: このメソッドはメインプロセスからのみ利用できます。

crashReporter.getLastCrashReport()

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

注意: このメソッドはメインプロセスからのみ利用できます。

crashReporter.getUploadedReports()

戻り値 CrashReport[]:

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

注意: このメソッドはメインプロセスからのみ利用できます。

crashReporter.getUploadToServer()

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

注意: このメソッドはメインプロセスからのみ利用できます。

crashReporter.setUploadToServer(uploadToServer)

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

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

注意: このメソッドはメインプロセスからのみ利用できます。

crashReporter.addExtraParameter(key, value)

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

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

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

注: パラメータはキーと値の長さに制限があります。 キー名の長さは 39 バイト以下、値の長さは 20320 バイト以下でなければなりません。 最大値より長い名前を持つキーは警告を出さずに無視されます。 キーや値が最大長より長ければ切り捨てられます。

crashReporter.removeExtraParameter(key)

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

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

crashReporter.getParameters()

戻り値 Record<String, String> - クラッシュリポーターの現在の「追加の」パラメータ。

Node の子プロセスで

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

process.crashReporter.start(options)

crashReporter.start() をご参照ください。

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

process.crashReporter.getParameters()

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

process.crashReporter.addExtraParameter(key, value)

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

process.crashReporter.removeExtraParameter(key)

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

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

クラッシュリポーターは、以下のデータを submitURLmultipart/form-dataPOST で送信します。

  • ver String - Electronのバージョン。
  • platform String - 例えば、'win32'。
  • process_type String - 例えば、'renderer'。
  • guid String - 例えば、'5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
  • _version String - package.json内のバージョン。
  • _productName String - crashReporteroptions内のproductName。
  • prod String - 基底にあるプロダクトの名前。 この場合は Electron です。
  • _companyName String - crashReporteroptions内のcompanyName。
  • upload_file_minidump File - minidumpフォーマットのクラッシュレポート。
  • crashReporteroptions内のextraオブジェクトの全ての最上位プロパティ。