symbolicate-crash-dump

クラッシュダンプをシンボリケートする

ネイティブの VS Code クラッシュダンプ（.dmp）を electron-minidump で、メソッド名を含む読みやすいバックトレースに変換します。

VS Code チームメンバー専用です。 内部向け Electron、Insiders、Stable ビルドのシンボルファイルは、非公開のリリースリポジトリにあります。macOS または Linux のデバイスが必要です。electron-minidump は Windows では動作しません。

前提条件

• クラッシュダンプファイル（*.dmp）。まだお持ちでない場合は、下記のクラッシュレポートの作成を参照してください。
• electron-minidump のグローバルインストール：

  npm install -g electron-minidump
  

• Insiders／Stable のシンボルを取得するには、非公開の microsoft/vscode-electron-prebuilt リポジトリにアクセスできる、認証済みの GitHub CLI（gh auth status）が必要です。

手順

1. 最初のシンボリケーションを実行する

これにより、electron-minidump のキャッシュが生成または更新され、不足しているシンボルが表示されます。

electron-minidump crash-file.dmp > symbolicated-output.log

symbolicated-output.log を確認します。バックトレースの先頭フレームを見て、フレームにモジュール名（例：Electron Framework）が表示されているものの、その後にメソッド名がない場合は、そのモジュールのシンボルが必要です。

一時的なダウンロードエラーが発生した場合は再試行してください。 electron-minidump は公開シンボルサーバーからシンボルをダウンロードするため、一時的なネットワークエラー（例：failed to download ... (code 56) または (code 28)）で実行に失敗することがあります。正常にダウンロードされたシンボルはキャッシュされるため、同じコマンドを再実行すれば、中断したところから再開できます。数回の再試行は想定されています。

for i in 1 2 3 4 5; do
    electron-minidump crash-file.dmp > symbolicated-output.log && break
    sleep 3
done

2. 適切なシンボルファイルを取得する

クラッシュを起こしたビルドに合ったシンボルの入手元を選びます。

クラッシュしたビルド	シンボルファイルの入手元
Insiders / Stable（内部向け Electron）	microsoft/vscode-electron-prebuilt releases
Code - OSS（OSS Electron）	electron/electron releases

microsoft/vscode-electron-prebuilt は非公開リポジトリです。そのため、この手順はチームメンバー専用です。認証なしでは通常のブラウザーや curl のリンクは 404 になるため、認証済みの GitHub CLI でアセットをダウンロードしてください（gh auth status でログイン状態を確認できます）。

# List releases (tagged by Electron version) to find the right tag:
gh release list --repo microsoft/vscode-electron-prebuilt

# Download just the symbol zip you need:
gh release download v42.5.0-14525058 \
    --repo microsoft/vscode-electron-prebuilt \
    --pattern "stable-symbols-v42.5.0-win32-x64.zip"

リリースには VS Code のバージョンではなく、Electron のバージョンがタグ付けされています。そのため、まずクラッシュした VS Code ビルドに含まれる Electron のバージョンを確認してください。これは、そのバージョンの .npmrc にある target= です（例：git show 1.128.0:.npmrc）。この値は package.json の electron devDependency と一致します。次に、品質、プラットフォーム、アーキテクチャに合ったシンボル zip を選びます。たとえば Electron 42.5.0 を使用した Stable Windows x64 のクラッシュには、stable-symbols-v42.5.0-win32-x64.zip が必要です（Insiders には insiders-symbols-… を使用してください）。Code - OSS のシンボルは公開されている electron/electron releases から入手でき、特別なアクセス権は不要です。

これらの zip は小さく、内容が限定されています。 *-symbols-*.zip に含まれるのは通常、Windows なら electron.exe.sym、libEGL.dll.sym、libGLESv2.dll.sym など、ファーストパーティのモジュールが数個だけです（他のプラットフォームでも同様のファイルが含まれます）。バックトレースに表示されるモジュールの多く、特に runtime.node や OS／サードパーティ製 DLL は、これらの zip には含まれていません。runtime.node のフレームは公開シンボルではシンボリケートできないことが多く、クラッシュがサードパーティ製モジュール内で発生した場合は、すべてのフレームにメソッド名が表示されることを期待せず、モジュール名で原因を特定してください（結果の読み方を参照してください）。

3. .sym ファイルを electron-minidump キャッシュにコピーする

キャッシュの場所：

"$(npm root -g)/electron-minidump/cache/breakpad_symbols"

Breakpad は、シンボルを <module>.pdb/<debug-id>/<module>.sym で識別します。<debug-id> はダンプとシンボル zip で完全に一致している必要があります。別のパイプライン実行でビルドされた同じバージョンの zip では ID が異なるため、使用されません。最初のパスの後、キャッシュには必要な各モジュール用の（空の）ディレクトリがすでにあります。モジュール名とハッシュを一致させる必要があります：

CACHE="$(npm root -g)/electron-minidump/cache/breakpad_symbols"
# The debug-id electron-minidump wants for a given module:
ls "$CACHE/electron.exe.pdb"     # e.g. DD081533CD7E33A44C4C44205044422E1

ダウンロードしたシンボルを解凍し、コピーする前に、zip 内に同じモジュール／ハッシュが存在することを確認してください。zip 内のレイアウトも <module>.pdb/<debug-id>/<module>.sym です。

例（Windows：同梱されているメインバイナリは Code.exe ですが、そのシンボルは electron.exe.sym から取得します）：

# Unzip somewhere, e.g. ~/stable-symbols/
unzip stable-symbols-v42.5.0-win32-x64.zip -d ~/stable-symbols

# Only copy if the debug-id matches what the cache expects.
# Keep the tilde outside quotes so it expands to your home directory:
HASH=DD081533CD7E33A44C4C44205044422E1
cp ~/stable-symbols/symbols/electron.exe.pdb/"$HASH"/electron.exe.sym \
   "$CACHE/electron.exe.pdb/$HASH/"

macOS で対応するモジュールは Electron Framework です（Electron Framework/<hash>/Electron Framework.sym）。最初のパスでメソッド名が不足していると報告された他のモジュールについても、zip に一致するハッシュの .sym が実際に含まれている場合に限り、同じ手順を繰り返してください。

一致するハッシュのシンボルが存在しない場合、そのモジュールのメソッド名は取得できません。これは、正確な electron.exe／Code.exe のハッシュが公開済みの zip に含まれていない、公式配布の Stable／Insiders ビルドや、runtime.node ではよくあることです。モジュールとプロセスに基づいてクラッシュの原因を特定してください（「結果の読み取り」を参照）。通常、サードパーティ製ソフトウェアの原因を特定するにはこれで十分です。

4. シンボル化を再実行する

electron-minidump crash-file.dmp > symbolicated-output.log

symbolicated-output.log のバックトレースに、メソッド名が表示されるはずです。一部のフレームにまだ名前がない場合は、シンボルが不足しているモジュールについて手順 2 に戻ってください。

結果の読み取り

バックトレースをシンボル化したら、次の 2 つの質問に答えて根本原因を特定します。

クラッシュが発生したモジュールはどれですか？

クラッシュしたスレッドの最上位フレーム（(crashed) とマークされています）と、モジュール名を確認します。

• VS Code／Electron のモジュール（Code.exe、runtime.node、Electron Framework、libnode、libffmpeg、V8 のフレーム）の場合、製品または Electron 内部の問題である可能性があります。
• サードパーティ製／OS のモジュール（プロセスに挿入されたウイルス対策ソフト、VPN、プロキシ、シェル拡張機能の DLL）の場合、クラッシュはほぼ間違いなく VS Code ではなく、そのソフトウェアが原因です。挿入された DLL はランタイムにフックするため、runtime.node／V8 のフレームの間に表示されることがよくあります。

ディスク上でモジュールが読み込まれている場所を確認し、サードパーティ製かどうかを確かめてください。Windows では、ダンプ内の strings にフルパスが含まれていることがよくあります。たとえば、VS Code のインストールディレクトリではなく、C:\WINDOWS\system32\ 配下やベンダーのフォルダーにある DLL などです。

strings -a crash-file.dmp | grep -i "<SuspectModule>" | sort -u

クラッシュしたプロセスはどれですか？

プロセスの種類から、メインプロセス、レンダラー／ウィンドウ、拡張機能ホストのいずれかを判断できます。最近の Electron では、拡張機能ホストは Node のユーティリティプロセス内で実行されます。そのため、クラッシュ時には「拡張機能ホスト」という名前のプロセスではなく、node.mojom.NodeService ユーティリティとして表示されます。

strings -a crash-file.dmp | grep -oiE "utility-sub-type=[a-zA-Z0-9._-]+|node\.mojom\.[A-Za-z]+|--type=[a-z-]+" | sort -u

マーカー	プロセス
node.mojom.NodeService / utility-sub-type=node.mojom.NodeService	拡張機能ホスト（Node ユーティリティプロセス）
--type=renderer	ワークベンチウィンドウ（レンダラー）
--type=gpu-process	GPU プロセス
(--type なし)	メインプロセス

報告された症状（例：「拡張機能ホストのクラッシュループ」）と照らし合わせ、NodeService ユーティリティのクラッシュに該当するか確認してください。

ダンプが複数ある場合は、それぞれをシンボル化してクラッシュの理由と最上位フレームを比較してください。ダンプ間でシグネチャが同一であれば、単一の再現可能な原因であることが確認できます。

クラッシュレポートの作成

まだ .dmp ファイルがない場合は、--crash-reporter-directory オプションを使って作成します。

1. VS Code のすべてのインスタンスを終了します。
2. コマンドラインから code --crash-reporter-directory <absolute-path> を実行します（Insiders ビルドの場合は code-insiders を使用してください）。
3. クラッシュを引き起こす操作を行います。
4. そのフォルダー内に *.dmp ファイルがあるか確認します。

シンボルが一致するビルドのクラッシュのみ、シンボリケートできます。Insiders／Stable のクラッシュには内部の Electron シンボルが必要です。ローカルのソースビルド（Code - OSS）のクラッシュには、OSS Electron シンボルが必要です。

リモート拡張機能ホストのクラッシュ（Linux、gdb）

リモートサーバーの拡張機能ホストで発生したネイティブクラッシュでは、electron-minidump の代わりにコアダンプと gdb を使用します。

1. サーバーを実行する前に、コアダンプを許可します：ulimit -c unlimited。
2. クラッシュを再現します。coredumpctl を使ってコアダンプを取得するか、/proc/sys/kernel/core_pattern に記載されたパスから取得します。
3. gdb で読み込み、出力を取得します：

   gdb -se <path-to-vscode-server>/node -c <path-to-core-file>
   

   次を実行して、出力を収集します：

   set pagination off
   info sharedlibrary
   info registers
   bt full
   disassemble
   

ヒント

• crash-file.dmp と symbolicated-output.log は使い捨ての生成物なので、リポジトリに含めないでください。
• キャッシュのパスは動的に変わるため、ホームディレクトリをハードコードせず、常に $(npm root -g) で解決してください。
• Breakpad はバージョン名ではなく、正確な debug-id でシンボルを照合します。シンボルを追加してもメソッド名が表示されない場合は、コピーした .sym のハッシュがキャッシュディレクトリで想定されているものと完全に一致するか確認し、シンボルの zip の品質（stable／insiders）、プラットフォーム（win32／darwin／linux）、アーキテクチャ（x64／arm64）も再確認してください。
• すべてのフレームをシンボリケートできるわけではありません。runtime.node やサードパーティ／OS のモジュールには公開シンボルがないことがよくあります。通常は、クラッシュしたモジュールとプロセスを特定できれば、根本原因の究明には十分です。