メインコンテンツへ飛ぶ

crashReporter

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

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

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

以下は、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)​

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 (任意) - 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() でクラッシュさせることで、crashReporter をテストできます。

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

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

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

crashReporter.getLastCrashReport()​

History

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

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

crashReporter.getUploadedReports()​

History

戻り値 CrashReport[]:

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

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

crashReporter.getUploadToServer()​

History

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

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

crashReporter.setUploadToServer(uploadToServer)​

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

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

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

crashReporter.addExtraParameter(key, value)​

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

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

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

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

crashReporter.removeExtraParameter(key)​

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

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

crashReporter.getParameters()​

戻り値 Record<string, string> - crashReporter の現在の「追加の」（extra）パラメータ。

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) をご覧ください。

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

クラッシュリポーターは、以下のデータを 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オブジェクトの全ての最上位プロパティ。