Partager via

Outil d’analyse du segment de mémoire (dotnet-gcdump)

Cet article s’applique à : ✔️ dotnet-gcdump version 10.0 et versions ultérieures

Installer

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

Notes

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

Synopsis

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

Descriptif

L’outil dotnet-gcdump global collecte les images mémoire GC (Garbage Collector ou récupérateur de mémoire) des processus .NET en direct à l’aide d’EventPipe. Les images mémoires GC sont créées en déclenchant un GC dans le processus cible, en activant des événements spéciaux et en régénérant le graphique des racines d’objet à partir du flux d’événements. Ce processus permet de collecter les images mémoires GC pendant l’exécution du processus et avec une surcharge minimale. Ces images mémoires sont utiles pour plusieurs scénarios :

  • Comparaison du nombre d’objets sur le segment de mémoire à plusieurs moments dans le temps.
  • Analyse des racines d’objets (répondre à des questions telles que « qu’est-ce qui a encore une référence pour ce type ? »).
  • Collecte de statistiques générales sur le nombre d’objets sur le tas.

Afficher l’image mémoire GC capturée à partir de dotnet-gcdump

Sous Windows, les fichiers .gcdump peuvent être affichés dans PerfView à des fins d’analyse ou dans Visual Studio. Actuellement, il n’existe aucun moyen d’ouvrir un .gcdump sur des plateformes non Windows.

Vous pouvez collecter plusieurs .gcdump et les ouvrir simultanément dans Visual Studio pour les comparer.

Paramètres

  • --version

    Affiche la version de l’utilitaire dotnet-gcdump.

  • -h|--help

    Affiche l’aide de la ligne de commande.

Commandes

Commande
dotnet-gcdump collect
dotnet-gcdump ps
rapport dotnet-gcdump

dotnet-gcdump collect

Collecte une image mémoire GC à partir d’un processus en cours d’exécution.

Avertissement

Pour parcourir le segment de mémoire GC, cette commande déclenche un nettoyage de la mémoire de génération 2 (complet), qui peut suspendre l’exécution pendant une longue période, en particulier lorsque le segment de mémoire GC est volumineux. N’utilisez pas cette commande dans les environnements sensibles aux performances lorsque le segment de mémoire GC est volumineux.

Synopsis

dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-file-path>] [-v|--verbose] [-t|--timeout <timeout>] [-n|--name <name>] [--dsrouter <ios|ios-sim|android|android-emu>]

Paramètres

  • -h|--help

    Affiche l’aide de la ligne de commande.

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

    ID de processus à partir duquel collecter l’image mémoire GC.

    Notes

    Sur Linux et macOS, l’utilisation de cette option nécessite l’application cible et dotnet-gcdump partage la même TMPDIR variable d’environnement. Dans le cas contraire, la commande expire.

  • -o|--output <gcdump-file-path>

    Chemin d’accès où les images mémoires GC collectés doivent être écrites. La valeur par défaut est .\YYYYMMDD_HHMMSS_<pid>.gcdump.

  • -v|--verbose

    Sortez le journal lors de la collecte de l’image mémoire GC.

  • -t|--timeout <timeout>

    Abandonnez la collecte de l’image mémoire GC si cela prend plus de quelques secondes. La valeur par défaut est 30.

  • -n|--name <name>

    Nom du processus à partir duquel collecter l’image mémoire GC.

    Notes

    Sur Linux et macOS, l’utilisation de cette option nécessite l’application cible et dotnet-gcdump partage la même TMPDIR variable d’environnement. Dans le cas contraire, la commande expire.

  • --diagnostic-port <port-address[,(listen|connect)]>

    Définit le port de diagnostic utilisé pour communiquer avec le processus à vider. dotnet-gcdump et le runtime .NET à l’intérieur du processus cible doivent accepter l’adresse de port, avec une écoute et l’autre connexion. dotnet-gcdump détermine automatiquement le port approprié lors de l’attachement à l’aide des options ou --process-id des --name options. Il est généralement nécessaire de spécifier explicitement le port lors de la communication à un processus qui s’exécute à l’intérieur d’un conteneur qui ne fait pas partie de l’espace de noms de processus actuel.

    Le port-address système d’exploitation diffère :

    • Linux et macOS : chemin d’accès à un socket de domaine Unix tel que /foo/tool1.socket.
    • Windows : chemin d’accès à un canal nommé tel que \\.\pipe\my_diag_port1.
    • Android, iOS et tvOS - un port IP :port tel que 127.0.0.1:9000.

    Par défaut, dotnet-gcdump écoute à l’adresse spécifiée. Vous pouvez demander à dotnet-gcdump de se connecter à la place en ajoutant ,connect après l’adresse. Par exemple, --diagnostic-port /foo/tool1.socket,connect vous connecterez à un processus de runtime .NET qui écoute le /foo/tool1.socket socket de domaine Unix.

  • --dsrouter <ios|ios-sim|android|android-emu>

    Démarre dotnet-dsrouter et se connecte à celui-ci. Nécessite l’installation de dotnet-dsrouter . Exécutez dotnet-dsrouter -h pour plus d’informations.

Notes

Pour collecter une image mémoire GC à l’aide de dotnet-gcdump, 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.

Examples

  • Collectez un vidage GC à partir d’un processus avec l’ID de processus 1902 :

    > dotnet-gcdump collect --process-id 1902
Writing gcdump to './20250601_121500_1902.gcdump'...
    Finished writing 5763432 bytes.

  • Collectez un vidage GC à partir d’un processus avec l’ID de processus 1902 et enregistrez-le dans un chemin personnalisé :

    > dotnet-gcdump collect --process-id 1902 --output ./myapp-dump.gcdump
Writing gcdump to './myapp-dump.gcdump'...
    Finished writing 5763432 bytes.

  • Collectez un vidage GC à partir d’un processus par nom avec une sortie détaillée :

    > dotnet-gcdump collect --name my-aspnet-server --verbose
[20:54:11] Starting gcdump collection...
[20:54:11] Triggering GC...
[20:54:12] Writing gcdump to './20250601_205412_4521.gcdump'...
    Finished writing 5763432 bytes.

  • Collectez un vidage GC avec un délai d’expiration personnalisé de 60 secondes :

    > dotnet-gcdump collect --process-id 1902 --timeout 60
Writing gcdump to './20250601_121500_1902.gcdump'...
    Finished writing 5763432 bytes.

dotnet-gcdump ps

Répertorie les processus dotnet pour lesquels les images mémoires GC peuvent être collectées. dotnet-gcdump 6.0.320703 et versions ultérieures affichent également les arguments de ligne de commande que chaque processus a démarrés, le cas échéant.

Synopsis

dotnet-gcdump 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-gcdump ps . La sortie que vous verrez est la suivante. Les arguments de ligne de commande, le cas échéant, sont affichés à l’aide de la version 6.0.320703 ou ultérieure de dotnet-gcdump.

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

dotnet-gcdump report <gcdump_filename>

Générez un rapport à partir d’une image mémoire GC générée précédemment ou d’un processus en cours d’exécution, puis écrivez dans stdout.

Synopsis

dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <HeapStat>]

Paramètres

  • -h|--help

    Affiche l’aide de la ligne de commande.

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

    ID de processus à partir duquel collecter l’image mémoire GC.

  • -t|--report-type <HeapStat>

    Type de rapport à générer. Options disponibles : heapstat (valeur par défaut).

Examples

  • Générez un rapport de statistiques de tas à partir d’un fichier créé .gcdump précédemment :

    > dotnet-gcdump report ./20250601_121500_1902.gcdump

    La sortie affiche les statistiques de type :

              Size (Bytes) Count       Type
        ============== =====       ====
        1,603,588,000  22,000,000  System.String
          201,096,000   2,010,000  System.Byte[]
          100,000,000   1,000,000  System.Char[]
           50,000,000     500,000  System.Object[]
           25,000,000     250,000  MyApp.Customer

  • Générez un rapport de statistiques de tas à partir d’un processus en cours d’exécution avec l’ID de processus 1902 :

    > dotnet-gcdump report --process-id 1902

Dépanner

  • Il n’existe aucune information de type dans le gcdump.

    Avant .NET Core 3.1, il existait un problème où un cache de type n’était pas effacé entre les gcdumps lorsqu’ils étaient appelés avec EventPipe. Les événements nécessaires à la détermination des informations de type n’ont donc pas été envoyés pour le deuxième gcdump et les suivants. Cela a été résolu dans .NET Core 3.1-preview2.

  • Les types COM et statique ne sont pas dans l’image mémoire GC.

    Avant .NET Core 3.1, il existait un problème où les types statique et COM n’étaient pas envoyés lorsque l’image mémoire GC était appelée via EventPipe. Cela a été résolu dans .NET Core 3.1.

  • dotnet-gcdump ne peut pas générer un fichier .gcdump car il manque des informations, par exemple, [Erreur] Exception pendant gcdump : System.ApplicationException : le fichier ETL affiche le début d’une image mémoire du segment de mémoire, mais pas sa finalisation.. Ou bien, le fichier .gcdump n’inclut pas le segment de mémoire entier.

    dotnet-gcdump fonctionne en collectant la trace des événements émis par le récupérateur de mémoire lors d’une collecte induite de génération 2. Si le segment de mémoire est suffisamment volumineux ou s’il n’y a pas assez de mémoire pour mettre à l’échelle les mémoires tampons d’événement, les événements nécessaires à la reconstruction du graphique du segment de mémoire à partir de la trace peuvent être supprimés. Dans ce cas, pour diagnostiquer les problèmes liés au segment de mémoire, il est recommandé de collecter une image mémoire du processus.

  • dotnet-gcdump semble provoquer un problème de mémoire insuffisante dans un environnement de mémoire limitée.

    dotnet-gcdump fonctionne en collectant la trace des événements émis par le récupérateur de mémoire lors d’une collecte induite de génération 2. La mémoire tampon pour la collecte d’événements appartient à l’application cible et peut atteindre 256 Mo. dotnet-gcdump utilise également la mémoire. Si votre environnement est limité en mémoire, veillez à tenir compte de ces facteurs lors de la collecte d’un gcdump pour éviter les erreurs.

  • Last updated on