Utilitaire de collecte et d’analyse de vidage (dotnet-dump)

  • Article

Cet article s’applique à : ✔️ dotnet-dump version 3.0.47001 et ultérieures

Notes

dotnet-dump pour macOS est uniquement pris en charge avec .NET 5 et versions ultérieures.

Installer

Il existe deux façons de télécharger et d’installer dotnet-dump :

Notes

Pour utiliser dotnet-dump sur une application x86, vous avez besoin d’une version x86 correspondante de l’outil.

Synopsis

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

Description

L’outil dotnet-dump global est un moyen de collecter et d’analyser des vidages sur Windows, Linux et macOS sans qu’aucun débogueur natif ne soit impliqué. Cet outil est important sur les plateformes comme Alpine Linux où un outil entièrement opérationnel lldb n’est pas disponible. L’outil dotnet-dump vous permet d’exécuter des commandes SOS pour analyser les incidents et le récupérateur de mémoire (GC), mais il ne s’agit pas d’un débogueur natif. Les éléments tels que l’affichage d’images de frames de pile natives ne sont pas pris en charge.

Options

  • --version

    Affiche la version de l’utilitaire dotnet-dump.

  • -h|--help

    Affiche l’aide en ligne de commande.

Commandes

Commande
dotnet-dump collect
analyse dotnet-dump
dotnet-dump ps

dotnet-dump collect

Capture un vidage d’un processus.

Synopsis

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

Options

  • -h|--help

    Affiche l’aide en ligne de commande.

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

    Spécifie le numéro d’ID de processus à partir duquel collecter une image mémoire.

  • -n|--name <name>

    Spécifie le nom du processus à partir duquel collecter une image mémoire.

  • --type <Full|Heap|Mini>

    Spécifie le type d’image mémoire, qui détermine les types d’informations collectées à partir du processus. Il existe trois types :

    • Full - Image mémoire la plus volumineuse contenant toutes les mémoires, y compris les images de module.
    • Heap - Image mémoire volumineuse et relativement complète contenant des listes de modules, des listes de threads, toutes les piles, des informations sur l’exception, la gestion des informations et toutes les mémoires, à l’exception des images mappées.
    • Mini - Petite image mémoire contenant des listes de modules, des listes de threads, des informations d’exception et toutes les piles.

    S’il n’est pas spécifié, Full est la valeur par défaut.

  • -o|--output <output_dump_path>

    Chemin d’accès complet et nom de fichier où l’image mémoire collectée doit être écrite. Vérifiez que l’utilisateur sous lequel le processus dotnet est exécuté dispose d’autorisations d’écriture dans le répertoire spécifié.

    Si elle n'est pas spécifiée :

    • La valeur par défaut est .\dump_YYYYMMDD_HHMMSS.dmp sur Windows.
    • La valeur par défaut est ./core_YYYYMMDD_HHMMSS sur Linux et macOS.

    AAAAMMJJ est Year/Month/Day et HHMMSS est Hour/Minute/Seconde.

  • --diag

    Active la journalisation des diagnostics de collecte d’image mémoire.

  • --crashreport

    Active la génération de rapports d’incident.

Notes

Sous Linux et macOS, cette commande s’attend à ce que l’application cible et dotnet-dump partagent la même variable d’environnement TMPDIR. Dans le cas contraire, la commande expire.

Notes

Pour collecter une image mémoire à l’aide de dotnet-dump, il faut l’exécuter en tant que même utilisateur que l’utilisateur exécutant le processus cible ou en tant que racine. Sinon, l’outil ne parvient pas à établir une connexion avec le processus cible.

analyse dotnet-dump

Démarre un interpréteur de commandes interactif pour explorer une image mémoire. L’interpréteur de commandes accepte diverses commandes SOS.

Synopsis

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

Arguments

  • <dump_path>

    Spécifie le chemin d’accès au fichier d’image mémoire à analyser.

Options

  • -c|--command <debug_command>

    Exécute la commande au démarrage. Plusieurs instances de ce paramètre peuvent être utilisées dans un appel pour chaîner des commandes. Les commandes sont exécutées dans l’ordre dans lequel elles sont fournies sur la ligne de commande. Si vous souhaitez que dotnet dump se termine après les commandes, votre dernière commande doit être « exit ».

Analyser les commandes SOS

Commande Fonction
analyzeoom Affiche les informations pour le dernier OOM qui s’est produit sur une requête d’allocation au tas GC.
clrmodules Répertorie les modules managés dans le processus.
clrstack Fournit uniquement une trace de la pile du code managé.
clrthreads Répertorie les threads managés en cours d’exécution.
clru Affiche un désassemblage annoté d’une méthode managée.
d ou readmemory Vide le contenu de la mémoire.
dbgout Active/désactive (-off) la journalisation SOS interne.
dso Affiche tous les objets managés recherchés dans les limites de la pile actuelle.
dumpalc Affiche des détails sur un AssemblyLoadContext pouvant être collecté sur lequel l’objet spécifié est chargé.
dumparray Affiche des détails sur un tableau managé.
dumpasync Affiche des informations sur les machines à états asynchrones sur le tas GC.
dumpassembly Affiche des détails sur un assembly.
dumpclass Affiche des informations sur la structure EEClass à l'adresse spécifiée.
dumpconcurrentdictionary Affiche le contenu du dictionnaire simultané.
dumpconcurrentqueue Affiche le contenu de file d’attente simultané.
dumpdelegate Affiche des informations sur un délégué.
dumpdomain Affiche des informations sur tous les assemblys au sein de tous les AppDomains ou de l’assembly spécifié.
dumpgcdata Affiche des informations sur les données GC.
dumpgen Affiche le contenu du tas pour la génération spécifiée.
dumpheap Affiche des informations sur le tas récupéré par le récupérateur de mémoire et des statistiques de collection concernant les objets.
dumpil Affiche le langage intermédiaire commun (CIL) associé à une méthode managée.
dumplog Écrit le contenu d'un journal de contrainte en mémoire dans le fichier spécifié.
dumpmd Affiche des informations sur la structure MethodDesc à l'adresse spécifiée.
dumpmodule Affiche des informations sur le module à l'adresse spécifiée.
dumpmt Affiche des informations sur la table de méthodes à l'adresse spécifiée.
dumpobj Affiche des informations sur l’objet à l’adresse spécifiée.
dumpruntimetypes Recherche tous les objets System.RuntimeType dans le tas GC et imprime le nom du type et la MethodTable auxquels ils font également référence.
dumpsig Vide la signature d’une méthode ou d’un champ spécifié par <sigaddr> <moduleaddr>.
dumpsigelem Vide un élément unique d'un objet de signature.
dumpstackobjects Affiche tous les objets managés recherchés dans les limites de la pile actuelle.
dumpvc Affiche des informations sur les champs d’une classe de valeur.
eeheap Affiche des informations sur la mémoire du processus consommée par les structures de données internes du runtime.
eestack S’exécute dumpstack sur tous les threads du processus.
eeversion Affiche des informations sur les versions du runtime et de SOS.
ehinfo Affiche les blocs de gestion des exceptions dans une méthode JIT.
exit ou quit Quitte le mode interactif.
finalizequeue Affiche tous les objets enregistrés pour la finalisation.
findappdomain Tente de résoudre l’AppDomain d’un objet GC.
gchandles Affiche des statistiques sur les handles du récupérateur de mémoire dans le processus.
gcheapstat Affiche des statistiques sur le récupérateur de mémoire.
gcinfo Affiche l’encodage GC JIT pour une méthode.
gcroot Affiche des informations sur les références (ou racines) à l’objet à l’adresse spécifiée.
gcwhere Affiche l’emplacement dans le tas GC de l’adresse spécifiée.
histclear Libère toutes les ressources utilisées par la famille de commandes Hist.
histinit Initialise les structures SOS du journal de contrainte enregistré dans l’élément débogué.
histobj Examine tous les enregistrements de réadressage du journal de contrainte et affiche la chaîne des réadressages de garbage collection qui ont pu mener à l’adresse passée comme un argument.
histobjfind Affiche toutes les entrées de journal qui référencent l’objet à l’adresse spécifiée.
histroot Affiche les informations liées aux promotions et aux réadressages de la racine spécifiée.
histstats Affiche les statistiques du journal de contrainte.
ip2md Affiche la structure MethodDesc à l'adresse spécifiée dans le code compilé juste-à-temps (JIT).
listnearobj Affiche l’objet qui précède et succède l’adresse spécifiée.
logopen Active la journalisation des fichiers de console.
logclose Désactive la journalisation des fichiers de console.
logging Active/désactive la journalisation SOS interne.
lm ou modules Affiche les modules natifs dans le processus.
name2ee Affiche les structures MethodTable et EEClass pour le type ou la méthode spécifié dans le module spécifié.
objsize Affiche la taille de l'objet spécifié.
parallelstacks Affiche la pile des threads fusionnés de la même façon que le panneau « Piles parallèles » de Visual Studio.
pathto Affiche le chemin d’accès GC de <root> à <target>.
pe ou printexception Affiche et met en forme les champs de tous les objets dérivés de la classe Exception à l'adresse spécifiée.
r ou registers Affiche les registres du thread.
runtimes Liste les runtimes de la cible ou change le runtime par défaut.
setclrpath Définit le chemin pour charger des fichiers dac/dbi coreclr en utilisant setclrpath <path>.
setsymbolserver Active la prise en charge du serveur de symboles.
sos Exécute différentes commandes de débogage coreclr. Utilisez la syntaxe sos <command-name> <args>. Pour plus d’informations, consultez « soshelp ».
soshelp ou help Affiche toutes les commandes disponibles.
soshelp <command> ou help <command> Affiche la commande spécifiée.
syncblk Affiche des informations sur le conteneur syncBlock.
taskstate Affiche un état de tâche dans un format lisible par l’utilisateur.
threadpool Affiche des informations sur le pool de threads d’exécution.
threadpoolqueue Affiche les éléments de travail du pool de threads mis en file d’attente.
threadstate Pretty imprime la signification d’un état de threads.
threads <threadid> ou setthread <threadid> Définit ou affiche l’ID de thread actuel pour les commandes SOS.
timerinfo Affiche des informations sur les minuteurs en cours d’exécution.
token2ee Affiche la structure MethodTable et la structure MethodDesc pour le jeton et le module spécifiés.
traverseheap Écrit les informations du tas dans un dans un format compris par le profileur CLR.
verifyheap Vérifie le tas GC pour détecter les signes d’altération.
verifyobj Vérifie l’objet passé comme argument à la recherche de signes d’altération.

Notes

Pour plus d’informations, consultez Extension de débogage SOS pour .NET.

dotnet-dump ps

Répertorie les processus dotnet à partir desquels les images mémoires peuvent être collectées. dotnet-dump version 6.0.320703 et versions ultérieures affichent également les arguments de ligne de commande avec lesquels chaque processus a été démarré, s’ils sont disponibles.

Synopsis

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

Exemple

Supposons que vous démarriez une application de longue durée à l’aide de la commande dotnet run --configuration Release. Dans une autre fenêtre, vous exécutez la commande dotnet-dump ps . La sortie que vous verrez est la suivante. Les arguments de ligne de commande, le cas échéant, sont affichés dans dotnet-dump version 6.0.320703 et ultérieures.

> dotnet-dump ps

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

Utilisation de dotnet-dump

La première étape consiste à collecter une image mémoire. Cette étape peut être ignorée si une image mémoire de cœur a déjà été générée. Le système d’exploitation ou la fonctionnalité de génération d’image mémoire intégrée du runtime .NET Core peut créer des images mémoire de cœur.

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

À présent, analysez l’image mémoire du cœur avec la commande 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.
>

Cette action fait apparaître une session interactive qui accepte des commandes telles que :

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

Pour voir une exception non gérée qui a tué votre application :

> 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

Dépannage des problèmes de collecte d’images mémoire

La collecte d’image mémoire nécessite que le processus puisse appeler ptrace. Si vous rencontrez des problèmes lors de la collecte des images mémoire, l’environnement sur lequel vous exécutez peut être configuré pour restreindre ces appels. Consultez nos images mémoire : FAQ pour obtenir des conseils de résolution des problèmes et des solutions potentielles aux problèmes courants.

Voir aussi