Hilfsprogramm zum Sammeln und Analysieren von Speicherabbildern (dotnet-dump)

  • Artikel

Dieser Artikel gilt für: ✔️ dotnet-dump 3.0.47001 und höhere Versionen

Hinweis

dotnet-dump für macOS wird nur mit .NET 5 und höheren Versionen unterstützt.

Installieren

Es gibt zwei Möglichkeiten, dotnet-dump herunterzuladen und zu installieren:

  • Globales dotnet-Tool:

    Verwenden Sie zum Installieren der neuesten Releaseversion des NuGet-Paketsdotnet-dump den Befehl dotnet tool install:

    dotnet tool install --global dotnet-dump

  • Direkter Download:

    Laden Sie die ausführbare Datei für das Tool herunter, die Ihrer Plattform entspricht:

    OS Plattform
    Windows x86 | x64 | Arm | Arm-x64
    Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Hinweis

Sie benötigen eine entsprechende x86-Version des Tools, um dotnet-dump für eine x86-App verwenden zu können.

Übersicht

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

Beschreibung

Mit dem globalen Tool dotnet-dump können Sie unter Windows, Linux und macOS ohne nativen Debugger Speicherabbilder sammeln und analysieren. Dieses Tool ist auf Plattformen wie z. B. Alpine Linux wichtig, bei denen kein voll funktionsfähiges Tool lldb verfügbar ist. Mit dem Tool dotnet-dump können Sie SOS-Befehle zum Analysieren von Abstürzen und dem Garbage Collector (GC) ausführen, es handelt sich jedoch nicht um einen nativen Debugger, sodass Elemente wie das Anzeigen von nativen Stapelrahmen nicht unterstützt werden.

Optionen

  • --version

    Mit dieser Option wird die Version des Hilfsprogramms „dotnet-dump“ angezeigt.

  • -h|--help

    Zeigt die Hilfe für die Befehlszeile an.

Befehle

Befehl
dotnet-dump collect
dotnet-dump analyze
dotnet-dump ps

dotnet-dump collect

Erfasst ein Speicherabbild von einem Prozess.

Übersicht

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

Optionen

  • -h|--help

    Zeigt die Hilfe für die Befehlszeile an.

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

    Hiermit wird die ID-Nummer des Prozesses angegeben, von dem ein Speicherabbild gesammelt werden soll.

  • -n|--name <name>

    Hiermit wird der Name des Prozesses angegeben, von dem ein Speicherabbild gesammelt werden soll.

  • --type <Full|Heap|Mini>

    Gibt den Speicherabbildtyp an, der festlegt, welche Arten von Informationen vom Prozess gesammelt werden. Es gibt drei Typen:

    • Full: Das größte Speicherabbild, das den gesamten Arbeitsspeicher einschließlich der Modulimages enthält
    • Heap: eine große und relativ umfassende Sicherung, die Modullisten, Threadlisten, alle Stapel, Ausnahmeinformationen, Handleinformationen und den gesamten Arbeitsspeicher mit Ausnahme von zugeordneten Images enthält.
    • Mini: eine kleine Sicherung, die Modullisten, Threadlisten, Ausnahmeinformationen und alle Stapel enthält.

    Wenn nichts anderes angegeben wird, wird als Standard Full verwendet.

  • -o|--output <output_dump_path>

    Der vollständige Pfad und der Dateiname, in den das gesammelte Speicherabbild geschrieben werden soll. Stellen Sie sicher, dass der Benutzer, unter dem der DotNet-Prozess ausgeführt wird, über Schreibberechtigungen für das angegebene Verzeichnis verfügt.

    Wenn nichts angegeben wird, gilt:

    • Unter Windows ist der Standard .\dump_JJJJMMTT_HHMMSS.dmp.
    • Unter Linux und macOS ist der Standard ./core_JJJJMMTT_HHMMSS.

    JJJJMMTT entspricht Jahr/Monat/Tag, und HHMMSS entspricht Stunde/Minute/Sekunde.

  • --diag

    Aktiviert die Diagnoseprotokollierung für die Speicherabbildsammlung.

  • --crashreport

    Aktiviert die Absturzberichtsgenerierung.

Hinweis

Unter Linux und macOS erwartet dieser Befehl, dass die Zielanwendung und dotnet-dump die gleiche TMPDIR-Umgebungsvariable verwenden. Andernfalls führt der Befehl zu einem Timeout.

Hinweis

Wenn Sie mit dotnet-dump ein Speicherabbild erfassen möchten, muss der Befehl vom Rootbenutzer oder dem Benutzer ausgeführt werden, der den Zielprozess ausführt. Andernfalls kann das Tool keine Verbindung mit dem Zielprozess herstellen.

dotnet-dump analyze

Startet eine interaktive Shell zum Durchsuchen eines Speicherabbilds. Die Shell akzeptiert verschiedene SOS-Befehle.

Übersicht

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

Argumente

  • <dump_path>

    Gibt den Pfad zu der Speicherabbilddatei an, die analysiert werden soll.

Tastatur

  • -c|--command <debug_command>

    Führt den Befehl beim Start aus. Mehrere Instanzen dieses Parameters können in einem Aufruf zum Verketten von Befehlen verwendet werden. Befehle werden in der Reihenfolge ausgeführt, in der sie in der Befehlszeile bereitgestellt werden. Wenn „dotnet dump“ nach den Befehlen beendet werden soll, muss der letzte Befehl „exit“ lauten.

SOS-Befehle zum Analysieren

Befehl Funktion
analyzeoom Zeigt Informationen zum letzten OOM-Ereignis an, das bei einer Speicherbelegungsanforderung an den Garbage Collection-Heap aufgetreten ist.
clrmodules Listet die verwalteten Module im Prozess auf.
clrstack Stellt eine Stapelüberwachung ausschließlich für verwalteten Code bereit.
clrthreads Listet die verwalteten Threads auf, die ausgeführt werden.
clru Zeigt eine mit Anmerkungen versehene Disassembly einer verwalteten Methode an.
d oder readmemory Sichert Arbeitsspeicherinhalte.
dbgout Aktiviert/deaktiviert (-off) die interne SOS-Protokollierung.
dso Zeigt alle innerhalb der Grenzen des aktuellen Stapels gefundenen verwalteten Objekte an.
dumpalc Zeigt Details zu einem entladbaren AssemblyLoadContext an, in den das angegebene Objekt geladen wird.
dumparray Zeigt Details zu einem verwalteten Array an.
dumpasync Zeigt Informationen zu Computern im asynchronen Status im Heap der Garbage Collection an.
dumpassembly Zeigt Details zu einer Assembly an.
dumpclass Zeigt Informationen zur EEClass-Struktur bei der angegebenen Adresse an.
dumpconcurrentdictionary Zeigt parallele Wörterbuchinhalte an.
dumpconcurrentqueue Zeigt parallele Warteschlangeninhalte an.
dumpdelegate Zeigt Informationen zu einem Delegaten an.
dumpdomain Zeigt Informationen zu allen Assemblys in allen Anwendungsdomänen oder in der angegebenen Domäne an.
dumpgcdata Zeigt Informationen zu Garbage Collection-Daten an.
dumpgen Zeigt den Heapinhalt für die angegebene Generation an.
dumpheap Zeigt Informationen zum Garbage Collector-Heap und Sammlungsstatistiken zu Objekten an.
dumpil Zeigt die allgemeine Zwischensprache (CIL) an, die einer verwalteten Methode zugeordnet ist.
dumplog Schreibt den Inhalt eines Belastungsprotokolls im Speicher in die angegebene Datei.
dumpmd Zeigt Informationen zu einer MethodDesc-Struktur bei der angegebenen Adresse an
dumpmodule Zeigt Informationen zum Modul bei der angegebenen Adresse an.
dumpmt Zeigt Informationen zur Methodentabelle bei der angegebenen Adresse an.
dumpobj Zeigt Informationen zum Objekt bei der angegebenen Adresse an.
dumpruntimetypes Sucht alle System.RuntimeType-Objekte im Garbage Collection-Heap und gibt den Typnamen und die MethodTable aus, auf die sie verweisen.
dumpsig Sichert die Signatur einer Methode oder eines Felds, die bzw. das durch <sigaddr> <moduleaddr> angegeben wird.
dumpsigelem Sichert ein einzelnes Element eines Signaturobjekts.
dumpstackobjects Zeigt alle innerhalb der Grenzen des aktuellen Stapels gefundenen verwalteten Objekte an.
dumpvc Zeigt Informationen zu den Feldern einer Wertklasse an.
eeheap Zeigt Informationen zu dem von internen Laufzeit-Datenstrukturen verwendeten Prozessspeicher an.
eestack Führt dumpstack für alle Threads im Prozess aus.
eeversion Zeigt Informationen zu den Runtime- und SOS-Versionen an.
ehinfo Zeigt die Ausnahmebehandlungsblöcke in einer angegebenen JIT-Methode an.
exit oder quit Beendet den interaktiven Modus.
finalizequeue Zeigt alle für den Abschluss registrierten Objekte an.
findappdomain Versucht, die Anwendungsdomäne eines Garbage Collection-Objekts aufzulösen.
gchandles Zeigt Statistiken über Garbage Collector-Handles im Prozess an.
gcheapstat Zeigt Statistiken zum Garbage Collector an.
gcinfo Zeigt die JIT-Garbage Collection-Codierung für eine Methode an.
gcroot Zeigt Informationen zu Verweisen auf das Objekt (oder Stämmen) bei der angegebenen Adresse an.
gcwhere Zeigt den Speicherort im Garbage Collection-Heap der angegebenen Adresse an.
histclear Gibt alle von der Familie der Hist-Befehle verwendeten Ressourcen frei.
histinit Initialisiert die SOS-Strukturen aus dem Belastungsprotokoll, die in der zu debuggenden Komponente gespeichert sind.
histobj Untersucht alle Aufzeichnungen von Belastungsprotokollumsetzungen und zeigt die Kette von Garbage Collection-Umsetzungen an, die möglicherweise zu der als Argument übergebenen Adresse geführt haben.
histobjfind Zeigt alle Protokolleinträge an, die auf das Objekt bei der angegebenen Adresse verweisen.
histroot Zeigt Informationen zu sowohl Heraufstufungen als auch Umsetzungen des angegebenen Stamms an.
histstats Zeigt Statistiken zum Belastungsprotokoll an.
ip2md Zeigt die MethodDesc-Struktur bei der angegebenen Adresse in JIT (Just-In-Time)-kompiliertem Code an.
listnearobj Zeigt das Objekt an, das der angegebenen Adresse vorausgeht und darauf folgt.
logopen Aktiviert die Protokollierung der Konsolendatei.
logclose Deaktiviert die Protokollierung der Konsolendatei.
logging Aktiviert/deaktiviert die interne SOS-Protokollierung.
lm oder modules Zeigt die nativen Module im Prozess an.
name2ee Zeigt die Strukturen MethodTable und EEClass für den angegebenen Typ oder die angegebene Methode im angegebenen Modul an.
objsize Zeigt die Größe des angegebenen Objekts an.
parallelstacks Zeigt den zusammengeführten Threadsstapel ähnlich wie im Visual Studio-Bereich „Parallele Stapel“ an.
pathto Zeigt den Garbage Collection-Pfad von <root> zu <target> an.
pe oder printexception Zeigt die Felder jedes Objekts an, das bei der angegebenen Adresse von der Exception-Klasse abgeleitet wird, und formatiert diese Felder.
r oder registers Zeigt die Register des Threads an.
runtimes Listet die Runtimes im Ziel auf oder ändert die Standardruntime.
setclrpath Legt den Pfad zum Laden von CoreCLR-DAC/DBI-Dateien mithilfe von setclrpath <path> fest.
setsymbolserver Aktiviert Unterstützung für den Symbolserver.
sos Führt verschiedene CoreCLR-Debugbefehle aus. Verwenden Sie die Syntax sos <command-name> <args>. Weitere Informationen finden Sie unter „soshelp“.
soshelp oder help Zeigt alle verfügbaren Befehle an.
soshelp <command> oder help <command> Zeigt den angegebenen Befehl an.
syncblk Zeigt die Informationen zum SyncBlock-Container an.
taskstate Zeigt einen Vorgangszustand in einem lesbaren Format an.
threadpool Zeigt Informationen zum Threadpool der Runtime an.
threadpoolqueue Zeigt Arbeitselemente für Threadpools in der Warteschlange an.
threadstate Gibt die Bedeutung eines Threadszustands mit automatischer Strukturierung und Einrückung aus.
threads <threadid> oder setthread <threadid> Legt die ID des aktuellen Threads für die SOS-Befehle fest oder zeigt diese an.
timerinfo Zeigt Informationen zu ausgeführten Timern an.
token2ee Zeigt die MethodTable-Struktur und die MethodDesc-Struktur für das angegebene Token und Modul an.
traverseheap Schreibt Heapinformationen in einem vom CLR-Profiler lesbaren Format in eine Datei.
verifyheap Überprüft den Garbage Collection-Heap auf Anzeichen einer Beschädigung.
verifyobj Überprüft das Objekt, das als Argument für Anzeichen für Beschädigungen übergeben wird.

Hinweis

Weitere Informationen finden Sie unter SOS-Debuggingerweiterung für .NET.

dotnet-dump ps

Hiermit werden die dotnet-Prozesse aufgelistet, für die Speicherabbilder erfasst werden können. Ab dotnet-dump-Version 6.0.320703 werden auch die Befehlszeilenargumente angezeigt, mit denen jeder Prozess gestartet wurde, sofern verfügbar.

Übersicht

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

Beispiel

Angenommen, Sie starten eine zeitintensive App mit dem Befehl dotnet run --configuration Release. In einem anderen Fenster führen Sie den Befehl dotnet-dump ps aus. Die Ausgabe sieht wie folgt aus. Sofern vorhanden, werden die Befehlszeilenargumente ab dotnet-dump-Version 6.0.320703 angezeigt.

> dotnet-dump ps

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

Verwenden von dotnet-dump

Der erste Schritt besteht im Sammeln eines Speicherabbilds. Dieser Schritt kann übersprungen werden, wenn bereits ein Kernspeicherabbild generiert wurde. Das Betriebssystem und die integrierte Speicherabbild-Generierungsfunktion der .NET Core-Runtime können Kernspeicherabbilder erstellen.

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

Analysieren Sie nun das Kernspeicherabbild mit dem Befehl 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.
>

Durch diese Aktion wird eine interaktive Sitzung aufgerufen, die Befehle wie die folgenden akzeptiert:

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

So zeigen Sie einen Ausnahmefehler an, der Ihre App beendet hat

> 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

Problembehandlung bei der Sammlung von Speicherabbildern

Die Sammlung von Speicherabbildern erfordert, dass der Prozess ptrace aufgerufen werden kann. Wenn Probleme beim Sammeln von Speicherabbildern auftreten, ist die Ausführungsumgebung möglicherweise so konfiguriert, dass solche Aufrufe eingeschränkt werden. Unter Häufig gestellte Fragen zu Speicherabbildern finden Sie Tipps zur Problembehandlung und mögliche Lösungen für häufige Probleme.

Weitere Informationen