ヒープ分析ツール (dotnet-gcdump)

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

インストール

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

• dotnet グローバル ツール:

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

  dotnet tool install --global dotnet-gcdump
  

• 直接ダウンロード:

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

  オペレーティングシステム (OS)	プラットフォーム
  ウィンドウズ	x86 | x64 | Arm | Arm64
  Linux	x64 | Arm | Arm64 | musl-x64 | musl-Arm64

構文

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

説明

dotnet-gcdump グローバル ツールで EventPipe を使用して、ライブ .NET プロセスの GC (ガベージ コレクター) ダンプを収集します。 GC ダンプを作成するには、ターゲット プロセスで GC をトリガーし、特殊なイベントを有効にし、イベント ストリームからオブジェクト ルートのグラフを再生成します。 このプロセスにより、プロセスの実行中のオーバーヘッドを最小限に抑えながら GC ダンプを収集できます。 このようなダンプは、いくつかのシナリオで役立ちます。

• 複数の時点でヒープ上にあるオブジェクト数を比較する。
• オブジェクトのルートを分析する ("この種類に対する参照がまだ残っているものはあるか" などの質問に回答する場合)。
• ヒープ上のオブジェクト数に関する一般的な統計情報を収集する。

dotnet-gcdump からキャプチャされた GC ダンプを表示する

Windows では、分析のために .gcdump で、または Visual Studio で ファイルを表示できます。 現在、Windows 以外のプラットフォームで .gcdump を開く方法はありません。

複数の .gcdump を収集し、それらを Visual Studio で同時に開いて、比較を行うことができます。

オプション

• --version

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

• -h|--help

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

コマンド

dotnet-gcdump collect

現在実行中のプロセスから GC ダンプを収集します。

構文

dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-file-path>] [-v|--verbose] [-t|--timeout <timeout>] [-n|--name <name>] [--dsrouter <ios|ios-sim|android|android-emu>]

オプション

• -h|--help

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

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

  GC ダンプを収集するプロセス ID。

  注意

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

• -o|--output <gcdump-file-path>

  収集された GC ダンプが書き込まれるパス。 既定値は .\YYYYMMDD_HHMMSS_<pid>.gcdump です。

• -v|--verbose

  GC ダンプの収集時にログを出力します。

• -t|--timeout <timeout>

  この秒数より長くかかる場合は、GC ダンプの収集をあきらめてください。 既定値は 30 です。

• -n|--name <name>

  GC ダンプを収集するプロセスの名前。

  注意

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

• --diagnostic-port <port-address[,(listen|connect)]>

  ダンプするプロセスとの通信に使用する 診断ポート を設定します。 ターゲット プロセス内の dotnet-gcdump と .NET ランタイムは、ポート アドレスに同意する必要があります。1 つはリッスンし、もう 1 つは接続している必要があります。 dotnet-gcdump は、 --process-id または --name オプションを使用して接続するときに、正しいポートを自動的に決定します。 通常は、現在のプロセス名前空間の一部ではないコンテナー内で実行されているプロセスと通信する場合にのみ、ポートを明示的に指定する必要があります。

  port-addressは OS によって異なります。

  • Linux と macOS - /foo/tool1.socketなどの Unix ドメイン ソケットへのパス。
  • Windows - \\.\pipe\my_diag_port1などの名前付きパイプへのパス。
  • Android、iOS、tvOS - 127.0.0.1:9000などの IP:port。

  既定では、dotnet-gcdump は指定されたアドレスでリッスンします。 代わりに、アドレスの後に ,connect を追加することで、dotnet-gcdump に接続を要求できます。 たとえば、 --diagnostic-port /foo/tool1.socket,connect は、 /foo/tool1.socket Unix ドメイン ソケットをリッスンしている .NET ランタイム プロセスに接続します。

• '--dsrouter {ios|ios-sim|android|android-emu}

  dotnet-dsrouter を起動し、それに接続します。 dotnet-dsrouter をインストールする必要があります。 詳細については、 dotnet-dsrouter -h を実行します。

dotnet-gcdump ps

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

構文

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

例

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

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

dotnet-gcdump report <gcdump_filename>

以前に生成された GC ダンプまたは実行中のプロセスからレポートを生成し、stdout に書き込みます。

構文

dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <HeapStat>]

オプション

• -h|--help

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

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

  GC ダンプを収集するプロセス ID。

• -t|--report-type <HeapStat>

  生成するレポートの種類。 使用可能なオプション: heapstat (既定値)。

トラブルシューティング

• gcdump に型情報はありません。

  .NET Core 3.1 より前のバージョンでは、EventPipe を使って呼び出されたときに、gcdump 間で型キャッシュがクリアされない問題がありました。 これにより、型情報を判別するために必要なイベントが 2 番目以降の gcdump に対して送信されなくなりました。 これは .NET Core 3.1-preview2 で修正されました。

• COM 型と静的な型は GC ダンプに含まれていません。

  .NET Core 3.1 より前のバージョンでは、EventPipe を介して GC ダンプが呼び出されたときに静的および COM 型が送信されない問題がありました。 これは .NET Core 3.1 で修正されました。

• dotnet-gcdump は、情報が不足しているため、.gcdump ファイルを生成できません。たとえば、[エラー] gcdump 中の例外: System.ApplicationException: ETL ファイルは、ヒープ ダンプの開始を示しますが、完了は示しません。 または、.gcdump ファイルにヒープ全体が含まれていません。

  dotnet-gcdump は、ジェネレーション 2 の誘導コレクション中にガベージ コレクターによって生成されたイベントのトレースを収集することによって機能します。 ヒープが十分に大きい場合、またはイベント バッファーをスケーリングするのに十分なメモリがない場合は、トレースからヒープ グラフを再構築するために必要なイベントが削除される可能性があります。 この場合、ヒープに関する問題を診断するには、プロセスのダンプを収集することをお勧めします。

• dotnet-gcdump は、メモリが制約された環境でメモリ不足の問題を引き起こす可能性があります。

  dotnet-gcdump は、ジェネレーション 2 の誘導コレクション中にガベージ コレクターによって生成されたイベントのトレースを収集することによって機能します。 イベント収集用のバッファーは、ターゲット アプリケーションによって所有され、最大 256 MB まで拡張できます。 dotnet-gcdump 自体でもメモリが使用されます。 環境にメモリの制約がある場合は、エラーを防ぐ目的で gcdump を収集する際に、これらの要因を必ず考慮してください。