Utilitaire de collecte et d’analyse de vidage (dotnet-dump)
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 :
outil global dotnet :
Pour installer la dernière version de version du
dotnet-dumppackage NuGet, utilisez la commande d’installation de l’outil dotnet :dotnet tool install --global dotnet-dumpTéléchargement direct :
Téléchargez l’exécutable de l’outil qui correspond à votre plateforme :
Système d''exploitation Plateforme Windows x86 | x64 | Arm | Arm-x64 Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64
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
--versionAffiche la version de l’utilitaire dotnet-dump.
-h|--helpAffiche 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|--helpAffiche 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é,
Fullest 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.
--diagActive la journalisation des diagnostics de collecte d’image mémoire.
--crashreportActive 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.
