傾印收集和分析公用程式 (dotnet-dump)

  • 發行項

本文適用於： ✔️ dotnet-dump 3.0.47001 版與更新版本

注意

只有 .NET 5 和更新版本支援 dotnet-dump macOS。

安裝

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

注意

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

概要

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

描述

dotnet-dump 全域工具可用來在 Windows、Linux 和 macOS 上收集及分析傾印，而且不需要任何原生偵錯工具。 此工具在 Alpine Linux 這類平台上很重要，因為這些平台沒有功能完整的 lldb。 dotnet-dump 工具可讓您執行 SOS 命令來分析損毀和記憶體回收行程 (GC)，但不是原生偵錯工具，因此不支援顯示原生堆疊框架這類作業。

選項。

  • --version

    顯示 dotnet-dump 公用程式的版本。

  • -h|--help

    顯示命令列說明。

命令

Command
dotnet-dump collect
dotnet-dump analyze
dotnet-dump ps

dotnet-dump collect

從處理序擷取傾印。

概要

dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--output] [--diag] [--crashreport]

選項。

  • -h|--help

    顯示命令列說明。

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

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

  • -n|--name <name>

    指定要從中收集傾印的處理序名稱。

  • --type <Full|Heap|Mini>

    指定傾印類型，以決定從處理序收集的資訊種類。 有三種類型:

    • Full - 最大的傾印，包含模組映像在內的所有記憶體。
    • Heap - 相對完整的大型傾印，包含模組清單、執行緒清單、所有堆疊、例外狀況資訊、控制代碼資訊，以及對應映像之外的所有記憶體。
    • Mini - 小型傾印，包含模組清單、執行緒清單、例外狀況資訊和所有堆疊。

    如果未指定，則預設為 Full。

  • -o|--output <output_dump_path>

    應寫入所收集之傾印的完整路徑和檔案名稱。 確認執行 dotnet 處理序的使用者具有指定目錄的寫入權限。

    如果未指定：

    • 在 Windows 上，預設為 \dump_YYYYMMDD_HHMMSS.dmp。
    • 在 Linux 和 macOS 上，預設為 /core_YYYYMMDD_HHMMSS。

    YYYYMMDD 為年/月/日，HHMMSS 是時/分/秒。

  • --diag

    啟用傾印收集診斷記錄。

  • --crashreport

    啟用損毀報告產生。

注意

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

注意

若要使用 dotnet-dump 收集傾印，其執行身分必須與執行目標處理序的使用者或根使用者相同。 否則，此工具將無法與目標處理序建立連線。

dotnet-dump analyze

啟動互動式殼層以探索傾印。 殼層接受各種 SOS 命令。

概要

dotnet-dump analyze <dump_path> [-h|--help] [-c|--command]

引數

  • <dump_path>

    指定要分析之傾印檔案的路徑。

選項。

  • -c|--command <debug_command>

    在啟動時執行命令。 此參數的多個執行個體用以鏈結命令。 命令會依照命令行上提供的順序執行。 如果您想要在命令之後結束 dotnet 傾印，則最後一個命令應該是 'exit'。

分析 SOS 命令

Command 函式
analyzeoom 顯示在 GC 堆積的配置要求上，最後發生之 OOM 的資訊。
clrmodules 列出處理序中的受控模組。
clrstack 僅提供 Managed 程式碼的堆疊追蹤。
clrthreads 列出正在執行的受控執行緒。
clru 顯示受控方法的已加註釋反組解碼。
d 或 readmemory 傾印記憶體內容。
dbgout 啟用/停用 (-off) 內部 SOS 記錄。
dso 顯示可在目前堆疊界限內找到的所有 Managed 物件。
dumpalc 顯示指定物件要載入其中的可收集 AssemblyLoadContext 其詳細資料。
dumparray 顯示受控陣列的詳細資料。
dumpasync 顯示記憶體回收堆積上非同步狀態機器的資訊。
dumpassembly 顯示組件的詳細資料。
dumpclass 顯示指定位址的 EEClass 結構資訊。
dumpconcurrentdictionary 顯示並行字典內容。
dumpconcurrentqueue 顯示並行佇列內容。
dumpdelegate 顯示委派的資訊。
dumpdomain 顯示所有 AppDomain 中所有組件或指定組件的資訊。
dumpgcdata 顯示 GC 資料的資訊。
dumpgen 顯示指定世代的堆積內容。
dumpheap 顯示記憶體回收堆積的資訊，以及物件的收集統計資料。
dumpil 顯示與受控方法建立關聯的 Microsoft 中繼語言 (MSIL)。
dumplog 將記憶體中壓力記錄檔的內容寫入指定的檔案。
dumpmd 顯示指定位址的 MethodDesc 結構資訊。
dumpmodule 顯示指定位址的模組資訊。
dumpmt 顯示指定位址的方法資料表資訊。
dumpobj 顯示指定位址的物件資訊。
dumpruntimetypes 尋找 GC 堆積中的所有 System.RuntimeType 物件，並列印其參考的類型名稱和 MethodTable。
dumpsig 傾印 <sigaddr> <moduleaddr> 所指定方法或欄位的特徵標記。
dumpsigelem 傾印特徵標記物件的單一元素。
dumpstackobjects 顯示可在目前堆疊界限內找到的所有 Managed 物件。
dumpvc 顯示實值類別欄位的資訊。
eeheap 顯示內部執行階段資料結構取用的處理序記憶體資訊。
eestack 在處理序的所有執行緒上執行 dumpstack。
eeversion 顯示執行階段和 SOS 版本的資訊。
ehinfo 顯示 JIT 方法中的例外狀況處理區塊。
exit 或 quit 結束互動模式。
finalizequeue 顯示所有已註冊為完成項的物件。
findappdomain 嘗試解析 GC 物件的 AppDomain。
gchandles 顯示處理序中記憶體回收行程控制代碼的統計資料。
gcheapstat 顯示記憶體回收行程的統計資料。
gcinfo 顯示方法的 JIT GC 編碼。
gcroot 顯示指定位址的物件參考 (或根目錄) 資訊。
gcwhere 顯示在指定位址之 GC 堆積中的位置。
histclear 釋出 Hist 命令系列所使用的任何資源。
histinit 初始化在偵錯項目中儲存之壓力記錄檔中的 SOS 結構。
histobj 會檢查所有壓力記錄檔重新配置記錄，並顯示可能會使位址被當做引數傳入之記憶體回收重新配置的鏈結。
histobjfind 顯示參考指定位址之物件的所有記錄檔項目。
histroot 顯示與指定之根的提升和重新配置都相關的資訊。
histstats 顯示壓力記錄統計資料。
ip2md 顯示在已進行 JIT 編譯之程式碼中之指定位址的 MethodDesc 結構。
listnearobj 顯示指定位址之前與之後的物件。
logopen 啟用主控台檔案記錄。
logclose 停用主控台檔案記錄。
logging 啟用/停用內部 SOS 記錄。
lm 或 modules 顯示處理序中的原生模組。
name2ee 顯示指定模組中之指定類型或方法的 MethodTable 和 EEClass 結構。
objsize 顯示所指定物件的大小。
parallelstacks 顯示與 Visual Studio [平行堆疊] 面板類似的合併執行緒堆疊。
pathto 顯示從 <root> 到 <target> 的 GC 路徑。
pe 或 printexception 顯示並格式化在所指定位址且衍生自 Exception 類別之任何物件的欄位。
r 或 registers 顯示執行緒的暫存器。
runtimes 列出目標中的執行階段，或變更預設執行階段。
setclrpath 設定使用 setclrpath <path> 載入 coreclr dac/dbi 檔案的路徑。
setsymbolserver 啟用符號伺服器支援。
sos 執行各種 coreclr 偵錯命令。 使用 sos <command-name> <args> 語法。 如需詳細資訊，請參閱 'soshelp'。
soshelp 或 help 顯示所有可用的命令。
soshelp <command> 或 help <command> 顯示指定的命令。
syncblk 顯示 SyncBlock 預留位置資訊。
taskstate 以人類可讀的格式顯示工作狀態。
threadpool 顯示執行階段執行緒集區的資訊。
threadpoolqueue 顯示排入佇列的執行緒集區工作項目。
threadstate 美化顯示執行緒狀態的意義。
threads <threadid> 或 setthread <threadid> 設定或顯示 SOS 命令的目前執行緒識別碼。
timerinfo 顯示執行中計時器的相關資訊。
token2ee 顯示指定權杖和模組的 MethodTable 結構和 MethodDesc 結構。
traverseheap 以 CLR 分析工具可了解的格式，將堆積資訊寫入檔案。
verifyheap 檢查 GC 堆積是否有損毀的跡象。
verifyobj 檢查傳遞為引數的物件以找出損毀的症狀。

注意

如需其他詳細資料，請參閱 .NET 的 SOS 偵錯延伸模組。

dotnet-dump ps

列出可從中收集傾印的 dotnet 處理序。 dotnet-dump 6.0.320703 版和更新版本也會顯示啟動每個處理序時所用的命令列引數 (如果有的話)。

概要

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

範例

假設您使用 dotnet run --configuration Release 命令，啟動了一個長時間執行的應用程式。 在另一個視窗中，您執行了 dotnet-dump ps 命令。 看到的輸出就會如下所示。 若為 dotnet-dump 6.0.320703 版和更新版本，會顯示命令列引數 (如果有的話)。

> dotnet-dump ps

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

使用 dotnet-dump

第一個步驟是收集傾印。 如果核心傾印已經產生，則可以略過此步驟。 作業系統或 .NET Core Runtime 的內建傾印產生功能都可以建立核心傾印。

$ dotnet-dump collect --process-id 1902
Writing minidump to file ./core_20190226_135837
Written 98983936 bytes (24166 pages) to core file
Complete

現在，使用 analyze 命令分析核心傾印：

$ dotnet-dump analyze ./core_20190226_135850
Loading core dump: ./core_20190226_135850
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

此動作會啟動可接受下列命令的互動式工作階段：

> clrstack
OS Thread Id: 0x573d (0)
    Child SP               IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]

若要查看終止了應用程式的未處理例外狀況：

> pe -lines
Exception object: 00007fb18c038590
Exception type:   System.Reflection.TargetInvocationException
Message:          Exception has been thrown by the target of an invocation.
InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP               IP               Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]

StackTraceString: <none>
HResult: 80131604

針對傾印收集問題進行疑難排解

傾印收集需要處理序能夠呼叫 ptrace。 如果您在收集傾印時遇到問題，您執行的環境可能已設定為限制這類呼叫。 請參閱我們的傾印：常見問題集，以取得常見問題的疑難排解祕訣和潛在解決方案。

另請參閱