Crashpad の設計概要

Crashpad Overview Design の日本語訳。 翻訳元は コミット 86aed0d4e037f9af6347b8b21daa37ea779234b2 の文書（2026 年 10 月 28 日取得）。 原文の TODO や将来予定を含め、その時点の記述を訳している。 本文と図の著作権は Copyright 2017 The Crashpad Authors。原文を日本語に翻訳し、サイト用の書式とリンクを調整した。 本文と図は Apache License 2.0 に基づく。

目次

目的

Crashpad は、クライアントのクラッシュ後のレポートを取得・保存し、上流の収集サーバーへ送信するためのライブラリである。クライアントがクラッシュ時点のプロセス状態を、できる限り忠実かつ広範囲に、最小限の手間で取得できるようにすることを目指している。

Crashpad はまた、診断を目的として、必要に応じてプロセス状態のダンプを取得する機能も提供する。

さらに、プロセスごとのキーと値のペアという形で、アプリケーション固有のメタデータをクラッシュ情報に付加するための最小限の機能を提供する。より高度なクライアントでは、拡張ポイントを通して、Crashpad を組み込む側がアプリケーション固有のメタデータをレポートにさらに付加できる。

背景

残念ながら、大規模なソフトウェアには、時折クラッシュを引き起こすバグが含まれているものである。バグがなくても、ソフトウェア間の互換性の問題によってプログラムが不安定になることがある。

世界中の何百万人ものユーザーに配布するクライアントソフトウェアで、バグや互換性の問題を修正するのは大変な作業である。ユーザーからの報告や手作業によるクラッシュの再現が役に立つ場合もあるが、報告があっても問題を簡単に再現できないことは多い。システムのバージョンやサードパーティー製ソフトウェアとの互換性、あるいは何らかの競合状態による問題など、理由はさまざまである。また、ユーザーは問題に遭遇しても報告しないことが多い。残念ながら、ほとんどのユーザーには適切なバグ報告を作成した経験がないため、報告の質も低いことが多い。

これまでのところ、最もよい解決策はクラッシュのテレメトリを自動収集することだった。これにより、ユーザーが手作業で報告する負担を取り除きながら、クラッシュ時点のハードウェアとソフトウェアの状態を取得できる。

TODO(siggi): この例を挙げる。

クラッシュのテレメトリでは、クラッシュ後のダンプを取得し、バックエンドの収集サーバーへ送信する。サーバー上では、ダンプからのスタック走査とシンボル解決を行い、さまざまな方法で評価・集計できる。これらの処理をクライアントではなく上流のサーバーで行うことには、いくつもの利点がある。精度の高いスタック走査には大容量のアンワインド情報が必要であり、アプリケーションのサイズを考えると、これをエンドユーザーに配布したくない場合がある。シンボル解決には、非常に大きくなることがあるデバッグシンボルへのアクセスが必要で、処理自体もほかのリソースを相当消費しうる。また、スタック走査もシンボル解決も行っていないクラッシュ後のダンプを収集サーバーへ送ることで、個々のダンプを詳細に解析できる。これは、クラッシュの原因となったバグの解決に必要になることが多い。

レポートを収集サーバーへ送信すると、原因ごとにクラッシュを集計できる。それにより、発生頻度やセキュリティへの潜在的な影響などの観点から、それぞれのクラッシュの重要性を評価できる。

クラッシュ後のダンプには、問題の診断と修正に十分な精度で、クラッシュ時点のプログラムの状態が含まれていなければならない。通常、プログラムの全状態は上流サーバーへ送るには大きすぎるため、ダンプには全状態のうちヒューリスティックに選んだ一部を記録する。

クラッシュしたプログラムは、状態が不確定である。実際、ヒープなどの大域的な状態が壊れたことが原因でクラッシュしている場合も多い。そのため、クラッシュしたプロセス内での実行をできるだけ少なくして、クラッシュレポートを生成することが重要である。このために利用できる機能は、OS ごとに異なる。

概要

Crashpad は、マシンとプログラムの状態をクラッシュ後のレポートに記録し、そのレポートをバックエンドの「収集サーバー」へ送ることに重点を置いた、クライアント側のライブラリである。クライアントアプリケーションに組み込んで使用する。概念的には、Crashpad はハンドラーとクライアントに分かれる。ハンドラーは、1 つ以上のクライアントとは別のプロセスで動作する。クラッシュ時にクライアントプロセスの状態のスナップショットを取得し、クラッシュダンプに保存して上流サーバーへ送信する役割を担う。クライアントは、自身のクラッシュを取得・アップロードしてもらうため、ハンドラーに登録する。iOS ではハンドラー用の別プロセスは存在しない。これは iOS の制約による。

Crashpad ハンドラー

Crashpad ハンドラーは、組み込み側のアプリケーションが用意するプロセス内でインスタンス化される。何らかの IPC によってクライアント自身を登録する手段を提供するほか、OS の支援が利用できる場合には、それを使ってクラッシュ通知がハンドラーに届くようにする。クラッシュが起きると、ハンドラーはクラッシュしたクライアントプロセスの状態のスナップショットを取得し、クラッシュ後のダンプとしてデータベースに書き込む。また、設定されていれば、ダンプを上流サーバーへ送信することもある。

Crashpad ハンドラーは、ビット数の異なるプロセスからの要求を処理し、ビット数をまたいでクラッシュダンプを生成できる。たとえば、ハンドラーが 64 ビットプロセスでクライアントが 32 ビットプロセスの場合や、その逆である。Windows では OS の制約により、32 ビットのハンドラーは 32 ビットのクライアントのクラッシュダンプしか生成できない。一方、64 ビットのハンドラーは 32 ビットプロセスについても、ほぼすべての詳細情報を取得できる。

Crashpad クライアント

Crashpad クライアントは、主に次の 2 つの機能を提供する。

  1. Crashpad ハンドラーへの登録。
  2. クラッシュ時の Crashpad ハンドラーへのメタデータの伝達。

Crashpad を組み込む側は、ロード可能なライブラリやプログラムファイルといった、1 つ以上の実行可能ファイルに Crashpad クライアントライブラリをリンクする。その後、クライアントプロセスは、何らかの IPC や OS 固有の支援機能を使って Crashpad ハンドラーに登録する。

クラッシュ時には、CrashpadInfo 構造体を介してメタデータが Crashpad ハンドラーへ伝えられる。Crashpad クライアントライブラリをリンクする各クライアントの実行可能モジュールには、CrashpadInfo 構造体が埋め込まれる。クライアントは、クラッシュとともに記録したい任意の状態で、この構造体を更新できる。

組み込み側、クライアントモジュール、Crashpad の関係

上の図は、組み込み側（水色）、クライアントモジュール（濃い青）、Crashpad（緑）の概念的な関係を示している。複数のクライアントモジュールが CrashpadInfo 構造体を持つことはできるが、登録は 1 回だけでよい。

詳細設計

要件

Crashpad の目的は、開発者がクラッシュの原因を診断し、可能であれば修正できるよう、マシン、OS、アプリケーションの状態を十分に詳細かつ忠実に取得することである。

各クラッシュレポートにはグローバルに一意な ID を割り当てる。これにより、ユーザーはクラッシュレポートをユーザーからの報告と関連づけたり、バグ報告に記載したりできる。

ユーザーの同意なしにクラッシュレポートが決してアップロードされないようにして、プライバシーを保護することが不可欠である。同様に、クライアントではないプロセスのレポートを Crashpad が取得・アップロードしないようにすることも重要である。

概念

TODO(siggi): ほかにも概念を追加する？

全体像

次の図は、Crashpad の各構成要素、その階層構造、クライアントによる想定上の使い方を大まかに示している。

Crashpad の階層構造

濃い青の箱がインターフェース、水色の箱が実装、灰色の部分が組み込み側のクライアントアプリケーションである。必然的に OS 固有になる実装も、可能な限り、Crashpad のほかの部分やクライアントに対しては OS に依存しないインターフェースを公開する。

登録

クライアントをハンドラーへ登録する具体的な方法は、OS ごとに異なる。

macOS

登録時に、クライアントは Crashpad ハンドラーが監視している Mach ポートを、自身の EXC_CRASH 例外ポートとして指定する。このポートは、新たにハンドラープロセスを起動するか、システムにすでに登録されているサービスを取得することで入手できる。登録はカーネルが管理し、デフォルトでは子プロセスの作成時に継承される。そのため、プロセスツリーの最上位のプロセスだけが登録すればよい。

Crashpad は、プロセスが既存のクラッシュハンドラーとの関連づけを解除する（登録を解除する）機能を提供する。これは、古いクライアントが更新後のバージョンを起動する場合などに必要となることがある。

iOS

iOS では、SIGABRT 用のシグナルハンドラーと、利用可能な例外の一部を対象とする Mach 例外ハンドラーの両方を登録する。これは iOS の制約による。

Windows

Windows には 2 つの登録方式がある。どちらも、クライアントプロセスのアドレス空間にある一連の構造体のアドレスをハンドラーに通知する。これらには、2 つの ExceptionInformation 構造体が含まれる。1 つはクラッシュしたプロセスのクラッシュ後のダンプを生成するためのもの、もう 1 つはクラッシュしていないプロセスのダンプを生成するためのものである。

通常の登録

通常の登録方式では、クライアントは事前に取り決めた名前の名前付きパイプに接続し、そのパイプに登録要求を書き込む。登録中に、ハンドラーは一連のイベントを作成して、登録するクライアントへ複製し、登録応答でハンドル値を返す。この処理はブロックする。

ハンドラーの初回作成

ハンドラーの作成と初期化によってクライアントの起動をブロックしないよう、ハンドラー作成時には別の登録方式を利用できる。この方式では、クライアントが一連のイベントハンドルを作成し、新しく作成したハンドラープロセスへ継承させる。ハンドラープロセスには、コマンドライン引数を通じて、ハンドル値と ExceptionInformation 構造体の位置が通知される。

Linux/Android

Linux では、登録はクライアントプロセスと Crashpad ハンドラーの間で接続されたソケットペアによって表される。このソケットペアは専用でもよいし、多数のクライアントプロセスで共有してもよい。

専用接続

クラッシュに応じてハンドラープロセスを起動する場合や、別のクライアントのために起動する場合は、専用接続がデフォルトの登録方式である。この方式は ptrace ブローカーを使うために必要であり、ptrace ブローカーは Android の隔離プロセスをトレースするために必要である。

共有接続

長時間稼働するハンドラーを使う場合、共有接続がデフォルトの方式である。同じ接続済みソケットペアを、任意の数のクライアントで共有できる。ソケットペアは、最初にハンドラーを起動するプロセスが作成する。その時点で、クライアント側のソケット端点を、継承などの適当な手段でほかのクライアントと共有できる。

例外の捕捉

クラッシュにつながる例外を Crashpad が捕捉する具体的な方法は、OS ごとに異なる。

macOS

macOS では、OS はクライアントプロセスの例外ポートに設定された Mach ポートを通して、クライアントのクラッシュをハンドラーへ通知する。例外はカーネルによって Mach ポートへ配送されるため、例外の発生時にクラッシュしたプロセス内でコードを実行する必要がなく、Crashpad ハンドラーだけで例外を処理できる。

iOS

iOS では、OS は Mach 例外ポートまたはシグナルハンドラーを通してクラッシュをハンドラーへ通知する。例外をプロセス内で処理するため、minidump ではなく中間ダンプファイルを生成する。詳細は iOS のプロセス内ハンドラーを参照。

Windows

Windows では、OS はクラッシュしたスレッドのコンテキストで例外を配送する。ハンドラーに例外を通知するため、Crashpad クライアントはクライアントプロセス内に UnhandledExceptionFilter（UEF）を登録する。例外が UEF まで伝播すると、UEF は例外情報とクラッシュしたスレッドの ID を、ハンドラーに登録済みの ExceptionInformation 構造体へ格納する。その後、イベントハンドルをシグナル状態にして、例外処理を開始するようハンドラーに通知する。

注意点
プロセス外での例外処理

Windows Error Reporting（WER）には、クライアントプロセスの例外を、クラッシュしたプロセスの外で処理するよう登録できる仕組みがある。残念ながら、この仕組みは扱いが難しく、上で挙げた注意点の多くも解消しない。詳細はこちら。

Linux/Android

Linux では、例外はクラッシュしたスレッドへシグナルとして配送される。Crashpad のシグナルハンドラーは、ソケット経由で Crashpad ハンドラーへメッセージを送り、クラッシュの発生と、クラッシュしたプロセスから読み出す例外情報の位置を通知する。共有ソケット接続では、通信は完全に一方向である。クライアントはダンプ要求をハンドラーへ送ったあと、ハンドラーが SIGCONT で応答するか、タイムアウトするまで待つ。専用ソケット接続では、ハンドラーはソケット経由で応答し、ptrace ブローカープロセスと通信できる。ブローカーはクラッシュしたプロセスから fork され、そのプロセスに対して ptrace 要求を実行し、得られた情報をソケット経由でハンドラーへ送る。

CrashpadInfo 構造体

CrashpadInfo 構造体は、クライアントからハンドラーへ情報を伝えるために使う。クライアントプロセス内の各実行可能モジュールは、CrashpadInfo 構造体を持つことができる。クラッシュが起きると、ハンドラーはクラッシュしたプロセスの全モジュールを走査し、存在するすべての CrashpadInfo 構造体を探す。この構造体は、実行可能ファイル内の特別な名前付きセクションにリンクされているため、ハンドラーは簡単に見つけられる。

CrashpadInfo 構造体には、識別用のマジック値、サイズフィールド、バージョンフィールドがある。これは、古いクライアントモジュールと新しいハンドラーの間で後方互換性を確保するためである。また、新しいクライアントと古いハンドラーの間で前方互換性が必要になるかもしれないが、まだそのような事態は起きていない。

CrashpadInfo 構造体には、クラッシュダンプに含めるメモリ量の上限、ハンドラーの動作を制御するいくつかの 3 値フラグ、アノテーション辞書へのポインターなどのプロパティが含まれる。

スナップショット

Snapshot は、Crashpad が扱うマシンや OS の構成要素を表現するインターフェースの層である。Snapshot の各具象実装では、クラッシュしたプロセスのメモリ内表現や minidump の内容など、異なるものをデータの実体として利用できる。

クラッシュダンプの作成

クラッシュダンプを作成するには、クラッシュしたプロセスからマシン、OS、アプリケーションの状態の一部を取得し、ハンドラープロセス内のメモリ上のスナップショット構造体へ格納する。通常、アプリケーションの全状態はディスクへの記録や上流サーバーへの送信には大きすぎるため、スナップショットにはヒューリスティックに選んだ一部の状態を含める。

取得する具体的な内容は OS ごとに異なるが、一般には以下を含む。

クラッシュダンプを取得する際は、まずクラッシュしたプロセスを一時停止し、次にハンドラープロセスでスナップショットを作成する。スナップショットには、プロセスにロードされているモジュールの CrashpadInfo 構造体も含まれる。その内容を使って、クラッシュダンプに記録する詳細度を制御する。

スナップショットを構築すると、minidump ファイルに書き出してデータベースに追加する。minidump ファイルの書き込み後、プロセスの一時停止を解除する。クラッシュによる場合は（クラッシュさせずにダンプを作成するようクライアントが要求した場合とは異なり）、その後 OS または Crashpad ハンドラーによってプロセスが強制終了される。

一般に、スナップショットの取得には対象 OS の内部に深く関わる必要がある。そのため、OS ごとに、この処理を行う一群の具象実装クラスがある。その多くは Snapshot のインターフェースを継承する。

Minidump

minidump の実装は、スナップショットを minidump 形式にシリアライズして、ディスク上のファイルに書き出す役割を担う。OS に依存しない Snapshot インターフェースを対象に動作するため、minidump の実装自体も OS に依存しない。

TODO(siggi): ここで 2 段階の書き込みと内容の順序について説明する。

データベース

Crashpad データベースには、一意なクラッシュクライアント識別子やアップロード有効化ビットなど、永続的なクライアント設定を格納する。クラッシュクライアント識別子は Crashpad が割り当てるものである。クライアントアプリケーションがユーザー、インストール、マシンなどを識別するために独自の識別子を使っている場合でも、それとは別のものである。クライアントアプリケーションがユーザーのアップロードへの同意を管理し、同意状況の変更を Crashpad に通知することを想定している。

一意なクライアント識別子は、データベースの作成時に設定する。その後、ハンドラーが収集するすべてのクラッシュレポートに記録され、上流サーバーへ伝えられる。

データベースに保存するクラッシュダンプの数と、その合計サイズの上限は設定できる。各クラッシュダンプについて、アップロードされたかどうかに関する付加情報を保存する。アップロードに成功したダンプについては、サーバーが割り当てた ID も保存する。

データベースは、バイナリ形式の内容を持つ「settings.dat」という名前の設定ファイル（ファイル形式については crashpad::Settings::Data を参照）と、クラッシュダンプを格納するディレクトリからなる。また、各クラッシュダンプには、アップロードの状態などに関するプロパティを付加する。これらのプロパティの保存方法は、プラットフォームによって異なる。

macOS

macOS の実装では、データベースのプロパティを minidump ファイルのファイルシステム拡張属性に保存するだけである。

iOS

iOS の実装も、minidump ファイルのデータベースプロパティをファイルシステム拡張属性に保存する。データベースとは別に、中間ダンプファイルもデータベースの隣に保存する。詳細は iOS の中間ダンプを参照。

Windows

Windows の実装では、データベースディレクトリの最上位にある「metadata」という名前のバイナリファイルへ、データベースのプロパティを保存する。

レポート形式

クラッシュレポートは Windows の minidump 形式で記録する。アノテーションなど、Crashpad 独自の追加機能をサポートするための拡張が含まれる。

収集サーバーへのアップロード

通信形式

当面、Crashpad は Breakpad の通信プロトコルを使う。これは基本的に、HTTP(S) 上で送る MIME マルチパートメッセージである。そのため、クラッシュしたプロセス内で見つかったすべての CrashpadInfo 構造体のアノテーションを統合し、フォームデータとして Breakpad の「クラッシュキー」を作成する。次に、クラッシュ後の minidump を、「upload_file_minidump」という名前の「application/octet-stream」添付ファイルとして追加する。送信時間を短縮し、送信の信頼性を高めるため、minidump を含むリクエストボディ全体を gzip 圧縮できる。慣例として、製品、バージョン、クライアント ID など、クライアントに関する情報をサーバーへ伝える一連の「クラッシュキー」が存在する。Crashpad は通常、これらの値を minidump ファイル自体に保存するが、Breakpad 形式のサーバーとの互換性のため、minidump から取り出してフォームデータとして送信する。

これは、既存の Breakpad ベースの上流サーバーが Crashpad のレポートを処理できるようにするための、一時的な互換措置である。将来的には通信プロトコルを変更し、アノテーションの重複した送信と処理をなくすことが想定されている。

トランスポート

組み込み側のクライアントは、ハンドラーに渡すコマンドラインを通じて、収集サーバーの URL を制御する。ハンドラーはクライアントの選択に応じて、HTTP または HTTPS でクラッシュをアップロードできる。中間者による盗聴からユーザーのプライバシーを守るため、クラッシュのアップロードには HTTPS を使うことを強く推奨する。

TODO(mmentovai): 証明書ピンニング。

アップロードの制限と再試行戦略

収集サーバーを DDoS から守り、クライアントにも過大なデータ転送を要求しないようにするため、ハンドラーはクライアント側でアップロードを制限する戦略を実装する。現時点の戦略は非常に単純で、アップロードを 1 時間に 1 回に制限し、失敗したアップロードは打ち切るだけである。

すべての制限を解除する実験が行われた。その集計データを分析すると、同じクライアントで短時間に複数回起きるクラッシュは、ほぼ常に同じ原因によるものだった。したがって、アップロードの制限によって失われる有用な情報はごく少ない。ただし、少なくともクラッシュの総回数を復元できることは非常に望ましい。

再試行しない点については、近く変更される見込みである。ネットワーク切断時やサスペンド・レジューム時などにしか起きないクライアントのクラッシュが、観測できないままになるためである。

拡張性

クライアントによる拡張

クライアントは、CrashpadInfo 構造体を操作することで、生成されるクラッシュレポートを 2 つの方法で拡張できる。拡張ポイントは次のとおりである。

  1. クラッシュレポートに含めるアドレス範囲の集合を指定する。
  2. クラッシュレポートに含めるユーザー定義の minidump ストリームを追加する。

どちらの場合も、クラッシュが起きる前に CrashpadInfo 構造体を更新しておく必要がある。

組み込み側による拡張

さらに、ハンドラーを組み込む側は、ハンドラーの main 関数へ「ユーザーストリームデータソース」のインスタンスを渡すことができる。minidump が書き込まれるたびに、これらのインスタンスが呼び出される。

各データソースは、独自のストリームを minidump に追加できる。その内容は、クラッシュに関係するシステムやアプリケーションの状態などから計算できる。

たとえば、クラッシュ時にシステムがメモリ不足などのリソース逼迫状態にあったかどうかがわかると便利なことがある。

依存関係

システムのヘッダーと API のほかに、Crashpad を Chromium の外で使う場合は、Chromium の base ライブラリのサブセットである「mini_chromium」に依存する。これは、Chromium 以外のクライアントが Chromium の base へ直接依存することなく Crashpad を使えるようにすると同時に、Chromium のプロジェクトがコードの重複や手間を最小限にして Crashpad を利用できるようにするためである。Chromium の一部として Crashpad を使う場合は、mini_chromium の代わりに Chromium 自身の base ライブラリを利用する。

欠点は、Crashpad が使う機能の範囲について、Chromium の base におけるインターフェースや実装の変更に mini_chromium を追従させ続けなければならないことである。

注意事項

TODO(anyone): 実施しなかったことや、より単純な方法ではうまくいかない理由を説明する必要があるかもしれない。ほかにも注意すべき点があれば記載する。

セキュリティ上の考慮事項

Crashpad は、サンドボックス化されたプロセスの状態を取得するために使われることがあり、minidump をディスクへ書き込む。そのため、セキュリティ境界をまたぐ可能性があり、クラッシュしたプロセスから読み出すすべてのデータを、極めて慎重に扱うことが重要である。Crashpad ハンドラーは、ポインターの有効性を検査し、指定された範囲内へのアクセスを強制する専用のアクセサーを使い、慎重にクライアントのアドレス空間へアクセスする。Crashpad ハンドラーへの情報の流れは、完全に一方向である。処理完了を示す 1 ビットの通知を除き、Crashpad がクライアントへ何かを伝え返すことはない。

プライバシー上の考慮事項

Crashpad は、クラッシュしたプロセスのメモリから任意の内容を取得しうる。これにはユーザー ID やパスワード、クレジットカード情報、URL、その他ユーザーがそのプログラムを信頼して預けたあらゆる内容が含まれる。クライアントプログラムは、クラッシュレポートをアップロードすることについてユーザーの同意を取得して尊重し、Crashpad データベースのアップロード状態を適切に管理しなければならない。

また、Crashpad は、ユーザーのシステム上にある任意のプロセスのクラッシュをアップロードしないよう注意しなければならない。そのため、ハンドラーに登録していないプロセスのクラッシュをアップロードすることは決してない。ただし、一部の OS では登録が子プロセスへ継承されることに注意が必要である。