堆積分析工具 (dotnet-gcdump)

發行項
02/28/2024

本文適用於：✔️ dotnet-gcdump 3.1.57502 版與更新版本

安裝

有兩種方法可下載並安裝 dotnet-gcdump：

dotnet 全域工具：

若要安裝最新發行版本的 dotnet-gcdumpNuGet 套件 (英文)，請使用 dotnet 工具安裝命令：
```
dotnet tool install --global dotnet-gcdump
```
直接下載：

下載適用於您平台的工具可執行檔：

OS 平台

Windows x86 | x64 | Arm | Arm64

Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64

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 中檢視 .gcdump 檔案以供分析，或在 Visual Studio 中檢視。目前無法在非 Windows 平台上開啟 .gcdump。

您可以收集多個 .gcdump，並在 Visual Studio 中同時開啟它們以比較體驗。

選項。

--version

顯示 dotnet-gcdump 公用程式的版本。
-h|--help

顯示命令列說明。

命令

Command
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 傾印的處理序識別碼。
-o|--output <gcdump-file-path>

應該寫入所收集 GC 傾印的路徑。預設為 .\YYYYMMDD_HHMMSS_<pid>.gcdump。
-v|--verbose

在收集 GC 傾印時輸出記錄。
-t|--timeout <timeout>

如果收集 GC 傾印所花費的時間超過此秒數，請放棄收集 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 傾印的處理序識別碼。
-t|--report-type <HeapStat>

要產生的報表類型。可用選項：heapstat (預設)。

疑難排解

gcdump 中沒有類型資訊。

在 .NET Core 3.1 之前，使用 EventPipe 叫用 gcdump 時，會發生叫用不同 gcdump 時未清除型別快取的問題。這會導致未將判斷類型資訊所需的事件傳送至第二個和後續 gcdumps。這已在 .NET Core 3.1-preview2 中修正。
GC 傾印中不存在COM 和靜態類型。

在 .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 以防止錯誤時考慮這些因素。