ダンプの収集と分析のユーティリティ (dotnet-dump)Dump collection and analysis utility (dotnet-dump)

この記事の対象: ✓ .NET Core 3.0 SDK 以降のバージョンThis article applies to: ✓ .NET Core 3.0 SDK and later versions

注意

macOS では、dotnet-dump はサポートされていません。dotnet-dump isn't supported on macOS.

dotnet-dump をインストールするInstalling dotnet-dump

dotnet-dump NuGet パッケージの最新のリリース バージョンをインストールするには、次のように dotnet tool install コマンドを使用します。To install the latest release version of the dotnet-dump NuGet package, use the dotnet tool install command:

dotnet tool install -g dotnet-dump

構文Synopsis

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

説明Description

dotnet-dump グローバル ツールを使用すると、Linux の lldb などの任意のネイティブ デバッガーを使用せずに、Windows と Linux のダンプを収集して分析できます。The dotnet-dump global tool is a way to collect and analyze Windows and Linux dumps without any native debugger involved like lldb on Linux. このツールは、lldb が完全に動作しない Alpine Linux などのプラットフォームで重要です。This tool is important on platforms like Alpine Linux where a fully working lldb isn't available. dotnet-dump ツールでは、SOS コマンドを実行してクラッシュとガベージ コレクター (GC) を分析できますが、これはネイティブのデバッガーではないため、ネイティブ スタック フレームの表示などの操作はサポートされていません。The dotnet-dump tool allows you to run SOS commands to analyze crashes and the garbage collector (GC), but it isn't a native debugger so things like displaying native stack frames aren't supported.

オプションOptions

  • --version

    dotnet-counters ユーティリティのバージョンを表示します。Displays the version of the dotnet-counters utility.

  • -h|--help

    コマンド ライン ヘルプを表示します。Shows command-line help.

コマンドCommands

コマンドCommand
dotnet-dump collectdotnet-dump collect
dotnet-dump analyzedotnet-dump analyze

dotnet-dump collectdotnet-dump collect

プロセスからダンプをキャプチャします。Captures a dump from a process.

構文Synopsis

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

オプションOptions

  • -h|--help

    コマンド ライン ヘルプを表示します。Shows command-line help.

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

    メモリ ダンプを収集するプロセスの ID 番号を指定します。Specifies the process ID number to collect a memory dump from.

  • --type <Heap|Mini>

    プロセスから収集する情報の種類を決定する、ダンプの種類を指定します。Specifies the dumb type, which determines the kinds of information that are collected from the process. 次の 2 つの種類があります。There are two types:

    • Heap: モジュールの一覧、スレッドの一覧、すべてのスタック、例外情報、ハンドル情報、およびマップされたイメージを除くすべてのメモリを含む、大規模で比較的包括的なダンプです。Heap - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images.
    • Mini: モジュールの一覧、スレッドの一覧、例外情報、およびすべてのスタックを含む小さいダンプです。Mini - A small dump containing module lists, thread lists, exception information, and all stacks.

    指定しない場合の既定は、Heap です。If not specified, Heap is the default.

  • -o|--output <output_dump_path>

    収集したダンプを書き込む完全なパスとファイル名。The full path and file name where the collected dump should be written.

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

    • Windows での既定は、 .\dump_YYYYMMDD_HHMMSS.dmp です。Defaults to .\dump_YYYYMMDD_HHMMSS.dmp on Windows.
    • Linux での既定は、 ./core_YYYYMMDD_HHMMSS です。Defaults to ./core_YYYYMMDD_HHMMSS on Linux.

    YYYYMMDD は、年/月/日で、HHMMSS は時間/分/秒です。YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second.

  • --diag

    ダンプの収集の診断ログを有効にします。Enables dump collection diagnostic logging.

dotnet-dump analyzedotnet-dump analyze

ダンプを検索する対話型シェルを開始します。Starts an interactive shell to explore a dump. このシェルでは、さまざまな SOS コマンドを受け入れます。The shell accepts various SOS commands.

構文Synopsis

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

引数Arguments

  • <dump_path>

    分析のためにファイルをダンプするパスを指定します。Specifies the path to the dump file to analyze.

オプションOptions

  • -c|--command <debug_command>

    起動時にシェルで実行するコマンドを指定します。Specifies the command to run in the shell on start.

SOS コマンドを分析するAnalyze SOS commands

コマンドCommand 関数Function
soshelp 使用可能なコマンドをすべて表示します。Displays all available commands
soshelp|help <command> 指定したコマンドを表示します。Displays the specified command.
exit|quit 対話モードを終了します。Exits interactive mode.
clrstack <arguments> マネージド コードのみのスタック トレースを提供します。Provides a stack trace of managed code only.
clrthreads <arguments> 実行中のマネージド スレッドを一覧表示します。Lists the managed threads running.
dumpasync <arguments> ガベージ コレクトされたヒープ上の非同期状態のマシンに関する情報を表示します。Displays information about async state machines on the garbage-collected heap.
dumpassembly <arguments> アセンブリに関する詳細を表示します。Displays details about an assembly.
dumpclass <arguments> 指定したアドレスにある EE クラスの構造体に関する情報を表示します。Displays information about a EE class structure at the specified address.
dumpdelegate <arguments> デリゲートに関する情報を表示します。Displays information about a delegate.
dumpdomain <arguments> すべての AppDomain と、そのドメイン内のすべてのアセンブリに関する情報を表示します。Displays information all the AppDomains and all assemblies within the domains.
dumpheap <arguments> ガベージ コレクトされたヒープと、オブジェクトの収集統計に関する情報を表示します。Displays info about the garbage-collected heap and collection statistics about objects.
dumpil <arguments> マネージド メソッドに関連付けられている Microsoft Intermediate Language (MSIL) を表示します。Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.
dumplog <arguments> メモリ内ストレス ログの内容を、指定したファイルに書き込みます。Writes the contents of an in-memory stress log to the specified file.
dumpmd <arguments> 指定したアドレスにある MethodDesc 構造体に関する情報を表示します。Displays information about a MethodDesc structure at the specified address.
dumpmodule <arguments> 指定したアドレスにある EE モジュール構造体に関する情報を表示します。Displays information about a EE module structure at the specified address.
dumpmt <arguments> 指定したアドレスにあるメソッド テーブルに関する情報を表示します。Displays information about a method table at the specified address.
dumpobj <arguments> 指定したアドレスにあるオブジェクトに関する情報を表示します。Displays info about an object at the specified address.
dso|dumpstackobjects <arguments> 現在のスタックの範囲内で見つかったすべてのマネージド オブジェクトを表示します。Displays all managed objects found within the bounds of the current stack.
eeheap <arguments> 内部のランタイム データ構造体によって消費されたプロセス メモリに関する情報を表示します。Displays info about process memory consumed by internal runtime data structures.
finalizequeue <arguments> 完了の目的で登録されているすべてのオブジェクトを表示します。Displays all objects registered for finalization.
gcroot <arguments> 指定したアドレスにあるオブジェクトへの参照 (またはルート) に関する情報を表示します。Displays info about references (or roots) to an object at the specified address.
gcwhere <arguments> 渡された引数の GC ヒープ内の場所を表示します。Displays the location in the GC heap of the argument passed in.
ip2md <arguments> 指定したアドレスにある JIT コード内の MethodDesc 構造体に関する情報を表示します。Displays the MethodDesc structure at the specified address in JIT code.
histclear <arguments> hist* コマンドのファミリによって使用されているすべてのリソースを解放します。Releases any resources used by the family of hist* commands.
histinit <arguments> デバッグ対象に保存されているストレス ログから SOS 構造体を初期化します。Initializes the SOS structures from the stress log saved in the debuggee.
histobj <arguments> <arguments> に関連するガベージ コレクションのストレス ログの再配置を表示します。Displays the garbage collection stress log relocations related to <arguments>.
histobjfind <arguments> 指定したアドレスにあるオブジェクトを参照するすべてのログ エントリを表示します。Displays all the log entries that reference an object at the specified address.
histroot <arguments> 指定したルートの上位変換と再配置の両方に関係する情報を表示します。Displays information related to both promotions and relocations of the specified root.
lm|modules プロセス内のネイティブ モジュールを表示します。Displays the native modules in the process.
name2ee <arguments> <argument> の MethodTable 構造体と EEClass 構造体を表示します。Displays the MethodTable structure and EEClass structure for the <argument>.
pe|printexception <arguments> アドレス <argument> で Exception クラスから派生したすべてのオブジェクトを表示します。Displays any object derived from the Exception class at the address <argument>.
setsymbolserver <arguments> シンボル サーバーのサポートを有効にします。Enables the symbol server support
syncblk <arguments> SyncBlock の所有者の情報を表示します。Displays the SyncBlock holder info.
threads|setthread <threadid> SOS コマンドの現在のスレッド ID を設定するか表示します。Sets or displays the current thread ID for the SOS commands.

dotnet-dump を使用するUsing dotnet-dump

まずはダンプを収集します。The first step is to collect a dump. コア ダンプを既に生成している場合、この手順をスキップできます。This step can be skipped if a core dump has already been generated. コア ダンプは、オペレーティング システムまたは .NET Core ランタイムに組み込まれているそれぞれのダンプ生成機能で作成できます。The operating system or the .NET Core runtime's built-in dump generation feature can each create core dumps.

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

ここで、次のように analyze コマンドを使用して、コア ダンプを分析します。Now analyze the core dump with the analyze command:

$ 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.
>

この操作により、次のようなコマンドを受け取る対話型セッションが開始されます。This action brings up an interactive session that accepts commands like:

> 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]

アプリを強制終了させた未処理の例外を表示するには、次のようにします。To see an unhandled exception that killed your app:

> 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

Docker 用の特別な手順Special instructions for Docker

ダンプの収集を Docker で実行している場合、SYS_PTRACE 機能 (--cap-add=SYS_PTRACE または --privileged) が必要です。If you're running under Docker, dump collection requires SYS_PTRACE capabilities (--cap-add=SYS_PTRACE or --privileged).

Microsoft .NET Core SDK Linux Docker イメージでは、一部の dotnet-dump コマンドで次の例外がスローされる場合があります。On Microsoft .NET Core SDK Linux Docker images, some dotnet-dump commands can throw the following exception:

未処理の例外:System.DllNotFoundException:共有ライブラリ 'libdl.so' またはその依存関係の 1 つを読み込めませんでした。Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies' exception.

"libc6-dev" パッケージをインストールすると、この問題を回避できます。To work around this problem, install the "libc6-dev" package.