共用方式為

堆積分析工具 (dotnet-gcdump)

本文適用於： ✔️ dotnet-gcdump 10.0 版和更新版本

安裝

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

注意

若要在 x86 應用程式上使用 dotnet-gcdump，就需要對應的 x86 版工具。

概要

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
dotnet-gcdump ps
dotnet-gcdump 報告

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>] [--dsrouter <ios|ios-sim|android|android-emu>]

選項。

  • -h|--help

    顯示命令列說明。

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

    要從中收集 GC 傾印的處理序識別碼。

    注意

    在 Linux 和 macOS 上，使用此選項需要目標應用程式並 dotnet-gcdump 共用相同的 TMPDIR 環境變數。 否則，命令將會逾時。

  • -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 環境變數。 否則，命令將會逾時。

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

    設定用來與要傾印之進程通訊的 診斷埠 。 目標進程內的 dotnet-gcdump 和 .NET 運行時間必須同意埠位址，其中一個接聽，另一個連接。 dotnet-gcdump 會在使用 --process-id 或 --name 選項附加時自動判斷正確的埠。 通常只有在與不在目前進程命名空間之容器內執行的進程通訊時，才需要明確指定埠。

    與 port-address OS 不同：

    • Linux 和 macOS - Unix 網域套接字的路徑，例如 /foo/tool1.socket。
    • Windows - 具名管道的路徑，例如 \\.\pipe\my_diag_port1。
    • Android、iOS 和 tvOS - IP：port，例如 127.0.0.1:9000。

    根據預設，dotnet-gcdump 會在指定的位址接聽。 您可以藉由在位址後面附加 ,connect ，要求 dotnet-gcdump 改為連線。 例如， --diagnostic-port /foo/tool1.socket,connect 會連線到接聽 Unix 網域套接字的 /foo/tool1.socket .NET 運行時間進程。

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

    啟動 dotnet-dsrouter 並連線到它。 需要安裝 dotnet-dsrouter 。 如需詳細資訊，請執行 dotnet-dsrouter -h 。

注意

若要使用 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 以防止錯誤時考慮這些因素。

  • Last updated on