Utilità di analisi e raccolta di dump (dotnet-dump)

  • Articolo

Questo articolo si applica a: ✔️ dotnet-dump versione 3.0.47001 e versioni successive

Nota

dotnet-dump per macOS è supportato solo con .NET 5 e versioni successive.

Installare

Esistono due modi per scaricare e installare dotnet-dump:

Nota

Per usare dotnet-dump in un'app x86, è necessaria una versione x86 corrispondente dello strumento.

Riepilogo

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

Descrizione

Lo strumento globale dotnet-dump è un modo per raccogliere e analizzare i dump in Windows, Linux e macOS senza alcun debugger nativo coinvolto. Questo strumento è importante su piattaforme come Alpine Linux in cui non è disponibile un lavoro lldb completo. Lo strumento dotnet-dump consente di eseguire comandi SOS per analizzare gli arresti anomali e il Garbage Collector (GC), ma non è un debugger nativo, motivo per cui gli elementi come la visualizzazione di stack frame nativi non sono supportati.

Opzioni

  • --version

    Visualizza la versione dell'utilità dotnet-dump.

  • -h|--help

    Mostra la Guida della riga di comando.

Comandi

Comando
raccogli dotnet-dump
analizza dotnet-dump
ps dotnet-dump

raccogli dotnet-dump

Acquisisce un dump da un processo.

Riepilogo

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

Opzioni

  • -h|--help

    Mostra la Guida della riga di comando.

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

    Specifica il numero ID del processo da cui raccogliere un dump.

  • -n|--name <name>

    Specifica il nome del processo da cui raccogliere un dump.

  • --type <Full|Heap|Mini>

    Specifica il tipo di dump, che determina i tipi di informazioni raccolti dal processo. Sono disponibili tre tipi:

    • Full - Il dump più grande contenente tutta la memoria, incluse le immagini del modulo.
    • Heap - Dump di grandi dimensioni e relativamente completo contenente elenchi di moduli, elenchi di thread, tutti gli stack, le informazioni sulle eccezioni, informazioni di gestione e tutta la memoria, a eccezione delle immagini mappate.
    • Mini - Un dump di dimensioni limitate contenente elenchi di moduli, elenchi di thread, informazioni sulle eccezioni e tutti gli stack.

    Se non specificato, Full è l'impostazione predefinita.

  • -o|--output <output_dump_path>

    Percorso completo e nome del file in cui deve essere scritto il dump raccolto. Verificare che l'utente per il quale è in esecuzione il processo dotnet disponga delle autorizzazioni di scrittura per la directory specificata.

    Se non specificata:

    • L'impostazione predefinita è .\dump_YYYYMMDD_HHMMSS.dmp in Windows.
    • L'impostazione predefinita è ./core_YYYYMMDD_HHMMSS in Linux e macOS.

    AAAAMMGG è Anno/Mese/Giorno e HHMMSS è Ore/Minuti/Secondi.

  • --diag

    Abilita la registrazione diagnostica della raccolta dump.

  • --crashreport

    Abilita la generazione di report di arresto anomalo del sistema.

Nota

In Linux e macOS questo comando prevede che l'applicazione di destinazione e dotnet-dump condividano la stessa variabile di ambiente TMPDIR. In caso contrario, il comando raggiungerà il timeout.

Nota

Per raccogliere un dump utilizzando dotnet-dump, è necessario che venga eseguito come stesso utente che esegue il processo target o come radice. In caso contrario, lo strumento non riuscirà a stabilire una connessione con il processo di destinazione.

analizza dotnet-dump

Avvia una shell interattiva per esplorare un dump. La shell accetta vari comandi SOS.

Riepilogo

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

Argomenti

  • <dump_path>

    Specifica il percorso del file dump da analizzare.

Opzioni

  • -c|--command <debug_command>

    Esegue il comando all'avvio. È possibile usare più istanze di questo parametro in una chiamata per concatenare i comandi. I comandi verranno eseguiti nell'ordine in cui vengono forniti nella riga di comando. Se si vuole che dotnet dump venga chiuso dopo i comandi, l'ultimo comando deve essere "exit".

Analizzare i comandi SOS

Comando Funzione
analyzeoom Visualizza le informazioni dell'ultimo OOM che si è verificato in una richiesta di allocazione all'heap GC.
clrmodules Elenca i moduli gestiti nel processo.
clrstack Fornisce l'analisi dello stack del solo codice gestito.
clrthreads Elenca i thread gestiti in esecuzione.
clru Visualizza un disassembly con le annotazioni di un metodo gestito.
d oppure readmemory Esegue il dump del contenuto della memoria.
dbgout Abilita/disabilita (-off) la registrazione SOS interna.
dso Visualizza tutti gli oggetti gestiti trovati nell'ambito dei limiti dello stack corrente.
dumpalc Contiene dettagli relativi a un assemblyLoadContext raccoglibile in cui viene caricato l'oggetto specificato.
dumparray Contiene dettagli relativi a una matrice gestita.
dumpasync Contiene informazioni sulle macchine a stati asincrone nell'heap di Garbage Collection.
dumpassembly Contiene dettagli relativi a un assembly.
dumpclass Contiene informazioni sulla struttura EEClass in corrispondenza dell'indirizzo specificato.
dumpconcurrentdictionary Illustra il contenuto del dizionario simultaneo.
dumpconcurrentqueue Illustra il contenuto della coda simultaneo.
dumpdelegate Contiene informazioni su un delegato.
dumpdomain Contiene informazioni su tutti gli assembly all'interno di tutti gli AppDomain o su quello specificato.
dumpgcdata Contiene informazioni sui dati GC.
dumpgen Illustra il contenuto dell'heap per la generazione specificata.
dumpheap Contiene informazioni sull'heap sottoposto a procedura di Garbage Collection e le statistiche di raccolta relative agli oggetti.
dumpil Visualizza il linguaggio intermedio comune (CIL) associato a un metodo gestito.
dumplog Scrive nel file specificato il contenuto di un log di stress in memoria.
dumpmd Contiene informazioni sulla struttura MethodDesc in corrispondenza dell'indirizzo specificato.
dumpmodule Contiene informazioni su un modulo in corrispondenza dell'indirizzo specificato.
dumpmt Contiene informazioni sulla tabella dei metodi in corrispondenza dell'indirizzo specificato.
dumpobj Contiene informazioni sull'oggetto in corrispondenza dell'indirizzo specificato.
dumpruntimetypes Trova tutti gli oggetti System.RuntimeType nell'heap GC e stampa inoltre il nome del tipo e la MethodTable a cui fanno riferimento.
dumpsig Esegue il dump della firma di un metodo o di un campo specificato da <sigaddr> <moduleaddr>.
dumpsigelem VisuEffettua il dump di un singolo elemento di un oggetto firma.
dumpstackobjects Visualizza tutti gli oggetti gestiti trovati nell'ambito dei limiti dello stack corrente.
dumpvc Contiene informazioni sui campi di una classe valore.
eeheap Contiene informazioni sulla memoria del processo utilizzata dalle strutture dei dati di runtime interne.
eestack Esegue dumpstack su tutti i thread del processo.
eeversion Contiene informazioni sulle versioni di runtime e SOS.
ehinfo Visualizza i blocchi di gestione delle eccezioni in un metodo JIT.
exit oppure quit Esce dalla modalità interattiva.
finalizequeue Visualizza tutti gli oggetti registrati per la finalizzazione.
findappdomain Tenta di risolvere l'AppDomain di un oggetto GC.
gchandles Visualizza le statistiche relative agli handle del Garbage Collector nel processo.
gcheapstat Illustra le statistiche relative al Garbage Collector.
gcinfo Illustra la codifica GC JIT per un metodo.
gcroot Contiene informazioni sui riferimenti (o radici) all’oggetto in corrispondenza dell'indirizzo specificato.
gcwhere Mostra la posizione nell'heap GC dell'indirizzo specificato.
histclear Rilascia tutte le risorse utilizzate dalla famiglia di comandi Hist.
histinit Inizializza le strutture SOS dal log di stress salvato nell'oggetto del debug.
histobj Esamina tutti i record delle rilocazioni del log di stress e visualizza la catena di rilocazioni di Garbage Collection che hanno potuto condurre all'indirizzo passato come argomento.
histobjfind Contiene tutte le voci del log che fanno riferimento all’oggetto in corrispondenza dell'indirizzo specificato.
histroot Visualizza informazioni correlate sia alle promozioni sia alle rilocazioni della radice specificata.
histstats Contiene le statistiche del log di stress.
ip2md Visualizza la struttura MethodDesc in corrispondenza dell'indirizzo specificato nel codice con compilazione JIT.
listnearobj Visualizza l'oggetto precedente e successivo all'indirizzo specificato.
logopen Abilita la registrazione dei file della console.
logclose Disabilita la registrazione dei file della console.
logging Abilita/disabilita la registrazione SOS interna.
lm oppure modules Visualizza i moduli nativi nel processo.
name2ee Visualizza le strutture MethodTable e EEClass per il tipo o il metodo specificato nel modulo specificato.
objsize Visualizza la dimensione dell'oggetto specificato.
parallelstacks Illustra gli stack di thread uniti in modo analogo al pannello "Stack paralleli" di Visual Studio.
pathto Visualizza il percorso GC da <root> a <target>.
pe oppure printexception Visualizza e formatta i campi di qualsiasi oggetto derivato dalla classe Exception in corrispondenza dell'indirizzo specificato.
r oppure registers Visualizza i registri del thread.
runtimes Elenca i runtime nella destinazione o modifica il runtime predefinito.
setclrpath Imposta il percorso per caricare i file coreclr dac/dbi usando setclrpath <path>.
setsymbolserver Abilita il supporto del server dei simboli.
sos Esegue vari comandi di debug coreclr. Usare la sintassi sos <command-name> <args>. Per altre informazioni, vedere "soshelp".
soshelp oppure help Visualizza tutti i comandi disponibili.
soshelp <command> oppure help <command> Visualizza il comando specificato.
syncblk Visualizza le informazioni sul supporto SyncBlock.
taskstate Mostra uno stato attività in un formato leggibile.
threadpool Contiene informazioni sul pool di thread di runtime.
threadpoolqueue Illustra gli elementi di lavoro del pool di thread in coda.
threadstate Stampa correttamente il significato di uno stato di thread.
threads <threadid> oppure setthread <threadid> Imposta o visualizza l'ID thread corrente per i comandi SOS.
timerinfo Visualizza informazioni sull'esecuzione dei timer.
token2ee Illustra la struttura MethodTable e la struttura MethodDesc per il token e il modulo specificati.
traverseheap Scrive informazioni sull'heap nel file specificato, in un formato leggibile dal profiler CLR.
verifyheap Controlla l'heap GC per verificare la presenza di segni di danneggiamento.
verifyobj Cerca segni di danneggiamento nell'oggetto passato come argomento.

Nota

Altri dettagli sono disponibili in SOS Debugging Extension for .NET (Estensione di debug SOS per .NET).

dotnet-dump ps

Elenca i processi dotnet da cui è possibile raccogliere i dump. La versione 6.0.320703 di dotnet-dump e versioni successive visualizza anche gli argomenti della riga di comando con cui è stato avviato ogni processo, se disponibile.

Riepilogo

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

Esempio

Si supponga di avviare un'app a esecuzione prolungata usando il comando dotnet run --configuration Release. In un'altra finestra si esegue il comando dotnet-dump ps. L'output visualizzato è il seguente. Gli argomenti della riga di comando, se presenti, vengono visualizzati nella versione 6.0.320703 di dotnet-dump e versioni successive.

> dotnet-dump ps

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

uso di dotnet-dump

Il primo passaggio consiste nel raccogliere un dump. Questo passaggio può essere ignorato se è già stato generato un dump principale. Il sistema operativo o la funzionalità di generazione di dump predefinita del runtime di .NET Core possono creare dump di base.

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

Analizzare ora il dump principale con il comando 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.
>

Questa azione conduce a una sessione interattiva che accetta comandi come:

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

Per visualizzare un'eccezione non gestita che ha terminato l'app:

> 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

Risoluzione dei problemi relativi alla raccolta di dump

La raccolta di dump richiede che il processo sia in grado di chiamare ptrace. Se si verificano problemi durante la raccolta dei dump, l'ambiente in cui viene effettuata l’esecuzione può essere configurato per limitare tali chiamate. Vedere Dump: domande frequenti per ottenere suggerimenti per la risoluzione dei problemi e possibili soluzioni ai problemi comuni.

Vedi anche