ダンプの収集と分析のユーティリティ (dotnet-dump)

この記事の対象: ✔️ dotnet-dump バージョン 3.0.47001 以降のバージョン

注意

macOS の dotnet-dump は、.NET 5 以降のバージョンでのみサポートされています。

インストール

dotnet-dump をダウンロードしてインストールするには、次の 2 つの方法があります。

  • dotnet グローバル ツール:

    dotnet-dump NuGet パッケージの最新のリリース バージョンをインストールするには、次のように dotnet tool install コマンドを使用します。

    dotnet tool install --global dotnet-dump
    
  • 直接ダウンロード:

    ご利用のプラットフォームに適したツールの実行可能ファイルをダウンロードします。

    OS プラットフォーム
    Windows x86 | x64 | Arm | Arm-x64
    Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64

注意

x86 アプリ上で dotnet-dump を使用するには、対応する x86 バージョンのツールが必要です。

構文

dotnet-dump [-h|--help] [--version] <command>

説明

dotnet-dump グローバル ツールを使用すると、任意のネイティブ デバッガーを使用せずに、Windows、Linux、macOS のダンプを収集して分析できます。 このツールは、lldb が完全に動作しない Alpine Linux などのプラットフォームで重要です。 dotnet-dump ツールでは、SOS コマンドを実行してクラッシュとガベージ コレクター (GC) を分析できますが、これはネイティブのデバッガーではないため、ネイティブ スタック フレームの表示などの操作はサポートされていません。

オプション

  • --version

    dotnet-dump ユーティリティのバージョンを表示します。

  • -h|--help

    コマンド ライン ヘルプを表示します。

コマンド

コマンド
dotnet-dump collect
dotnet-dump analyze
dotnet-dump ps

dotnet-dump collect

プロセスからダンプをキャプチャします。

構文

dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--output] [--diag] [--crashreport]

オプション

  • -h|--help

    コマンド ライン ヘルプを表示します。

  • -p|--process-id <PID>

    ダンプを収集するプロセスの ID 番号を指定します。

  • -n|--name <name>

    ダンプを収集するプロセスの名前を指定します。

  • --type <Full|Heap|Mini>

    プロセスから収集する情報の種類を決定する、ダンプの種類を指定します。 次の 3 種類があります。

    • Full - モジュール イメージを含むメモリをすべて含む最大のダンプ。
    • Heap: モジュールの一覧、スレッドの一覧、すべてのスタック、例外情報、ハンドル情報、およびマップされたイメージを除くすべてのメモリを含む、大規模で比較的包括的なダンプです。
    • Mini: モジュールの一覧、スレッドの一覧、例外情報、およびすべてのスタックを含む小さいダンプです。

    指定しない場合の既定は、Full です。

  • -o|--output <output_dump_path>

    収集したダンプを書き込む完全なパスとファイル名。 dotnet プロセスを実行しているユーザーに指定のディレクトリに対する書き込み許可が与えられるようにします。

    指定していない場合は、次になります。

    • Windows での既定は、 .\dump_YYYYMMDD_HHMMSS.dmp です。
    • Linux および macOS での既定は、./core_YYYYMMDD_HHMMSS です。

    YYYYMMDD は、年/月/日で、HHMMSS は時間/分/秒です。

  • --diag

    ダンプの収集の診断ログを有効にします。

  • --crashreport

    クラッシュ レポートの生成を有効にします。

注意

Linux と macOS 上でこのコマンドを使用するには、ターゲット アプリケーションと dotnet-dump で同じ TMPDIR 環境変数が共有されることが前提とされています。 それ以外の場合、このコマンドはタイムアウトします。

注意

dotnet-dump を使用してダンプを収集するには、ターゲット プロセスを実行しているユーザーと同じユーザーとして、またはルートとしてそれを実行する必要があります。 それ以外の場合、このツールでターゲット プロセスとの接続を確立することはできません。

dotnet-dump analyze

ダンプを検索する対話型シェルを開始します。 このシェルでは、さまざまな SOS コマンドを受け入れます。

構文

dotnet-dump analyze <dump_path> [-h|--help] [-c|--command]

引数

  • <dump_path>

    分析のためにファイルをダンプするパスを指定します。

[オプション]

  • -c|--command <debug_command>

    起動時にコマンドを実行します。 1 つの呼び出しでこのパラメーターの複数インスタンスを使って、コマンドを連鎖させることができます。 コマンドは、コマンド ラインで指定した順番に実行されます。 このコマンドの後に dotnet dump を終了する場合は、最後のコマンドを 'exit' にする必要があります。

SOS コマンドを分析する

コマンド 機能
analyzeoom GC ヒープへの割り当て要求で発生した最後の OOM の情報を表示します。
clrmodules プロセス内のマネージド モジュールを一覧表示します。
clrstack マネージド コードのみのスタック トレースを提供します。
clrthreads 実行中のマネージド スレッドを一覧表示します。
clru マネージド メソッドの注釈付き逆アセンブリを表示します。
d または readmemory メモリの内容をダンプします。
dbgout 内部 SOS ログを有効/無効 (-off) にします。
dso 現在のスタックの範囲内で見つかったすべてのマネージド オブジェクトを表示します。
dumpalc 指定したオブジェクトが読み込まれる先の収集可能な AssemblyLoadContext に関する詳細を表示します。
dumparray マネージド配列に関する詳細を表示します。
dumpasync ガベージ コレクトされたヒープ上の非同期状態機械に関する情報を表示します。
dumpassembly アセンブリに関する詳細を表示します。
dumpclass 指定されたアドレスにある EEClass 構造体に関する情報を表示します。
dumpconcurrentdictionary 同時実行辞書の内容を表示します。
dumpconcurrentqueue 同時実行キューの内容を表示します。
dumpdelegate デリゲートに関する情報を表示します。
dumpdomain すべての AppDomain または指定されたドメイン内のすべてのアセンブリに関する情報を表示します。
dumpgcdata GC データに関する情報を表示します。
dumpgen 指定した世代のヒープの内容を表示します。
dumpheap ガベージ コレクトされたヒープと、オブジェクトの収集統計に関する情報を表示します。
dumpil マネージド メソッドに関連付けられている共通中間言語 (CIL) を表示します。
dumplog メモリ内ストレス ログの内容を、指定したファイルに書き込みます。
dumpmd 指定されたアドレスにある MethodDesc 構造体に関する情報を表示します。
dumpmodule 指定されたアドレスにあるモジュールに関する情報を表示します。
dumpmt 指定されたアドレスにあるメソッド テーブルに関する情報を表示します。
dumpobj 指定されたアドレスにあるオブジェクトに関する情報を表示します。
dumpruntimetypes GC ヒープ内のすべての System.RuntimeType オブジェクトを検索し、それらが参照する型名と MethodTable を出力します。
dumpsig <sigaddr> <moduleaddr> で指定されたメソッドまたはフィールドのシグネチャをダンプします。
dumpsigelem シグネチャ オブジェクトの 1 つの要素をダンプします。
dumpstackobjects 現在のスタックの範囲内で見つかったすべてのマネージド オブジェクトを表示します。
dumpvc 値クラスのフィールドに関する情報を表示します。
eeheap 内部のランタイム データ構造体によって消費されたプロセス メモリに関する情報を表示します。
eestack プロセス内のすべてのスレッドに対して dumpstack を実行します。
eeversion ランタイムと SOS のバージョンに関する情報を表示します。
ehinfo JIT されたメソッドの例外処理ブロックを表示します。
exit または quit 対話モードを終了します。
finalizequeue 完了の目的で登録されているすべてのオブジェクトを表示します。
findappdomain GC オブジェクトの AppDomain の解決を試みます。
gchandles プロセス内のガベージ コレクター ハンドルに関する統計を表示します。
gcheapstat ガベージ コレクターに関する統計情報を表示します。
gcinfo メソッドの JIT GC エンコードを表示します。
gcroot 指定されたアドレスにあるオブジェクトへの参照 (またはルート) に関する情報を表示します。
gcwhere 指定されたアドレスの GC ヒープ内の場所を表示します。
histclear Hist コマンドのファミリによって使用されているすべてのリソースを解放します。
histinit デバッグ対象に保存されているストレス ログから SOS 構造体を初期化します。
histobj すべてのストレス ログ再配置レコードを調べて、引数として渡されたアドレスになった可能性のあるガベージ コレクション再配置のチェーンを表示します。
histobjfind 指定されたアドレスにあるオブジェクトを参照するすべてのログ エントリを表示します。
histroot 指定したルートの上位変換と再配置の両方に関係する情報を表示します。
histstats ストレス ログの統計を表示します。
ip2md JIT コンパイルされたコード内の指定したアドレスにある MethodDesc 構造体を表示します。
listnearobj 指定されたアドレスの前および後にあるオブジェクトを表示します。
logopen コンソール ファイル ログを有効にします。
logclose コンソール ファイル ログを無効にします。
logging 内部 SOS ログを有効/無効にします。
lm または modules プロセス内のネイティブ モジュールを表示します。
name2ee 指定されたモジュール内の指定の型またはメソッドの MethodTable および EEClass 構造体を表示します。
objsize 指定したオブジェクトのサイズを表示します。
parallelstacks マージされたスレッド スタックを Visual Studio の '並列スタック' パネルと同様に表示します。
pathto <root> から <target> への GC パスを表示します。
pe または printexception 指定したアドレスにある Exception クラスから派生したすべてのオブジェクトのフィールドが表示および書式設定されます。
r または registers スレッドのレジスタを表示します。
runtimes ターゲット内のランタイムを一覧表示するか、既定のランタイムを変更します。
setclrpath setclrpath <path> を使用して coreclr dac/dbi ファイルを読み込むためのパスを設定します。
setsymbolserver シンボル サーバーのサポートを有効にします。
sos さまざまな coreclr デバッグ コマンドを実行します。 構文 sos <command-name> <args> を使用します。 詳細については、「soshelp」を参照してください。
soshelp または help 使用可能なコマンドをすべて表示します。
soshelp <command> または help <command> 指定したコマンドを表示します。
syncblk SyncBlock の所有者の情報を表示します。
taskstate タスクの状態を人間が判読できる形式で表示します。
threadpool ランタイム スレッド プールに関する情報を表示します。
threadpoolqueue キューに登録されたスレッド プールの作業項目を表示します。
threadstate Pretty はスレッド状態の意味を出力します。
threads <threadid> または setthread <threadid> SOS コマンドの現在のスレッド ID を設定するか表示します。
timerinfo 実行タイマーに関する情報を表示します。
token2ee 指定されたトークンとモジュールの MethodTable 構造体と MethodDesc 構造体を表示します。
traverseheap ヒープ情報を、CLR プロファイラーが解釈できる形式でファイルに書き込みます。
verifyheap 破損の兆候がないか GC ヒープを確認します。
verifyobj 引数として渡されたオブジェクトで破損の兆候を調べます。

注意

その他の詳細は、「.NET 用 SOS デバッガー拡張」に記載されています。

dotnet-dump ps

ダンプを収集できる dotnet プロセスを一覧表示します。 dotnet-dump バージョン 6.0.320703 以降のバージョンでは、各プロセスが開始されたコマンド ライン引数 (該当する場合) も表示されます。

構文

dotnet-dump ps [-h|--help]

コマンド dotnet run --configuration Release を使用して、実行時間の長いアプリを起動するとします。 別のウィンドウで dotnet-dump ps コマンドを実行します。 表示される出力は次のとおりです。 コマンドライン引数 (ある場合) は、dotnet-dump バージョン 6.0.320703 以降で表示されます。

> dotnet-dump ps

  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

dotnet-dump を使用する

まずはダンプを収集します。 コア ダンプを既に生成している場合、この手順をスキップできます。 コア ダンプは、オペレーティング システムまたは .NET Core ランタイムに組み込まれているそれぞれのダンプ生成機能で作成できます。

$ dotnet-dump collect --process-id 1902
Writing minidump to file ./core_20190226_135837
Written 98983936 bytes (24166 pages) to core file
Complete

ここで、次のように analyze コマンドを使用して、コア ダンプを分析します。

$ dotnet-dump analyze ./core_20190226_135850
Loading core dump: ./core_20190226_135850
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

この操作により、次のようなコマンドを受け取る対話型セッションが開始されます。

> clrstack
OS Thread Id: 0x573d (0)
    Child SP               IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]

アプリを強制終了させた未処理の例外を表示するには、次のようにします。

> pe -lines
Exception object: 00007fb18c038590
Exception type:   System.Reflection.TargetInvocationException
Message:          Exception has been thrown by the target of an invocation.
InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP               IP               Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]

StackTraceString: <none>
HResult: 80131604

ダンプ収集に関する問題の解決

ダンプ収集では、プロセスで ptrace を呼び出せることが必要になります。 ダンプを収集できない場合、そのような呼び出しを制限するように環境が構成されている可能性があります。 一般的な問題の解決ヒントと考えられる解決策については、「ダンプ: FAQ」を参照してください。

関連項目