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

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

インストール

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

• dotnet グローバル ツール:

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

  dotnet tool install --global dotnet-gcdump
  

• 直接ダウンロード:

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

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

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

Options

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

オプション

• -h|--help

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

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

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

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

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

• -v|--verbose

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

• -t|--timeout <timeout>

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

• -n|--name <name>

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

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 を収集する際に、これらの要因を必ず考慮してください。