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

  • [アーティクル]

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

インストール

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

  • dotnet グローバル ツール:

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

    dotnet tool install --global dotnet-gcdump

  • 直接ダウンロード:

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

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

注意

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

構文

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
dotnet-gcdump ps
dotnet-gcdump report

dotnet-gcdump collect

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

警告

GC ヒープをウォークするために、このコマンドによって第 2 世代の (完全な) ガベージ コレクションがトリガーされます。これにより、特に GC ヒープが大きい場合に、ランタイムが長時間中断されるおそれがあります。 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 ダンプを収集するプロセスの名前。

注意

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

注意

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