この記事の対象: ✔️ dotnet-dump バージョン 3.0.47001 以降のバージョン
注意
macOS の dotnet-dump は、.NET 5 以降のバージョンでのみサポートされています。
インストール
dotnet-dump をダウンロードしてインストールするには、次の 2 つの方法があります。
dotnet グローバル ツール:
dotnet-dumpNuGet パッケージの最新のリリース バージョンをインストールするには、次のように dotnet tool install コマンドを使用します。dotnet tool install --global dotnet-dump直接ダウンロード:
ご利用のプラットフォームに適したツールの実行可能ファイルをダウンロードします。
オペレーティングシステム (OS) プラットフォーム ウィンドウズ 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) を分析できますが、これはネイティブのデバッガーではないため、ネイティブ スタック フレームの表示などの操作はサポートされていません。
オプション
--versiondotnet-dump ユーティリティのバージョンを表示します。
-h|--helpコマンド ライン ヘルプを表示します。
コマンド
| コマンド |
|---|
| dotnet-dump 収集 |
| dotnet-dump analyze |
| dotnet-dump ps |
dotnet-dump 収集
プロセスからダンプをキャプチャします。
構文
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 を使用してダンプを収集するには、ターゲット プロセスを実行しているユーザーと同じユーザーとして、またはルートとしてそれを実行する必要があります。 それ以外の場合、このツールでターゲット プロセスとの接続を確立することはできません。
注意
完全ダンプまたはヒープ ダンプを収集すると、ターゲット プロセスの実質的な仮想メモリに OS がページングされる可能性があります。 メモリ制限が適用されたコンテナーでターゲット プロセスが実行されている場合、メモリ使用量が増加すると、制限を超えた場合に OS がコンテナーを終了する可能性があります。 メモリ制限が十分に高く設定されていることを確認するためのテストをお勧めします。 もう 1 つのオプションは、環境でサポートされている場合は、ダンプ収集の前に制限を一時的に変更または削除することです。
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」を参照してください。
関連項目
GitHub で Microsoft と共同作業する
このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。 詳細については、共同作成者ガイドを参照してください。
.NET