Partager via

EventPipe

EventPipe est un composant d'exécution qui peut être utilisé pour collecter des données de suivi, comme ETW ou perf_events. L'objectif d'EventPipe est de permettre aux développeurs .NET de tracer facilement leurs applications .NET sans avoir à s'appuyer sur des composants à privilèges élevés spécifiques à la plate-forme, tels que ETW ou perf_events.

EventPipe est le mécanisme derrière de nombreux outils de diagnostic et peut être utilisé pour consommer des événements émis par le runtime, ainsi que des événements personnalisés écrits avec EventSource.

Cet article est une vue d’ensemble générale d’EventPipe. Il décrit quand et comment utiliser EventPipe, et comment le configurer en fonction de vos besoins.

Concepts de base d’EventPipe

EventPipe agrège les événements émis par les composants de l'environnement d'exécution, tels que le compilateur Just-In-Time ou le collecteur de mémoire, ainsi que les événements écrits à partir d'instances EventSource dans les bibliothèques et le code utilisateur.

Les événements sont ensuite sérialisés au format de fichier .nettrace et peuvent être écrits directement dans un fichier ou diffusés via un port de diagnostic pour une consommation hors processus.

Pour en savoir plus sur le format NetTrace, consultez la documentation du format NetTrace.

EventPipe vs ETW/perf_events

EventPipe fait partie du runtime .NET et est conçu pour fonctionner de la même manière sur toutes les plateformes supportées par .NET Core. Cela permet aux outils de suivi basés sur EventPipe, tels que dotnet-counters, dotnet-gcdump et dotnet-trace, de fonctionner de manière fluide sur les plateformes.

Toutefois, étant donné que EventPipe est un composant intégré au runtime, son étendue est limitée au code managé et au runtime lui-même. Sans autres outils de trace, les événements EventPipe incluent des traces de pile avec uniquement des informations de trame de code géré. Pour obtenir des événements à partir d’autres bibliothèques en mode utilisateur non managées, l’échantillonnage du processeur pour le code natif ou les événements de noyau, utilisez des outils de suivi spécifiques au système d’exploitation tels que ETW ou perf_events. Sur Linux, l’outil perfcollect permet d’automatiser l’utilisation de perf_events et LTTng.

À compter de .NET 10, EventPipe sur Linux peut émettre des événements en tant que user_events, ce qui permet la collecte d’événements managés, d’événements de système d’exploitation/noyau et de pile d’appels natives dans une seule trace unifiée. Ce mode nécessite des privilèges d’administrateur/racine et le noyau Linux 6.4+. Pour plus d’informations, consultez dotnet-trace collect-linux.

Une autre différence majeure entre EventPipe et ETW/perf_events est la nécessité d'avoir les privilèges admin/root. Pour tracer une application en utilisant ETW ou perf_events, vous devez être administrateur/root. À l’aide d’EventPipe standard, vous pouvez tracer des applications tant que le traceur (par exemple) dotnet-traceest exécuté en tant qu’utilisateur identique à l’utilisateur qui a lancé l’application. Le mode EventPipe (user_events) décrit précédemment nécessite des privilèges d’administrateur/racine, car il interagit avec l’infrastructure de suivi au niveau du système d’exploitation.

Le tableau suivant résume les différences entre EventPipe et ETW/perf_events.

Fonctionnalité EventPipe EventPipe (événements_utilisateur) ETW perf_events
Multiplateforme Oui Non (uniquement sur les distributions Linux prises en charge) Non (uniquement sur Windows) Non (uniquement sur les distributions Linux prises en charge)
Exiger le privilège d’administrateur/racine Non Oui Oui Oui
Peut obtenir des événements de système d’exploitation/noyau Non Oui Oui Oui
Peut résoudre des piles d’appels natives Non Oui Oui Oui

Utiliser EventPipe pour suivre votre application .NET

Vous pouvez utiliser EventPipe pour suivre votre application .NET de plusieurs façons :

Une fois que vous avez produit un fichier nettrace qui contient vos événements EventPipe, vous pouvez afficher le fichier dans PerfView ou Visual Studio. Sur les plateformes non-Windows, vous pouvez convertir le fichier nettrace dans un format de suivi speedscope ou Chromium à l’aide de la commande dotnet-trace convert et l’afficher avec speedscope ou Chrome DevTools.

Vous pouvez également analyser les traces EventPipe par programme avec TraceEvent.

Outils qui utilisent EventPipe

Il s’agit du moyen le plus simple d’utiliser EventPipe pour suivre votre application. Pour en savoir plus sur l’utilisation de chacun de ces outils, reportez-vous à la documentation de chaque outil.

  • dotnet-counters vous permet de surveiller et de collecter différentes métriques émises par le runtime .NET et les bibliothèques principales, ainsi que les métriques personnalisées que vous pouvez écrire.

  • dotnet-gcdump vous permet de collecter des vidages de tas mémoire GC de processus actifs afin d'analyser le tas managé d'une application.

  • dotnet-trace vous permet de collecter des traces d’applications pour en analyser les performances.

Effectuer un suivi à l’aide de variables d’environnement

Le mécanisme préféré pour l’utilisation d’EventPipe consiste à utiliser dotnet-trace ou la bibliothèque Microsoft.Diagnostics.NETCore.Client.

Toutefois, vous pouvez utiliser les variables d’environnement suivantes pour configurer une session EventPipe sur une application et faire en sorte qu’elle écrive la trace directement dans un fichier. Pour arrêter le suivi, quittez l’application.

  • DOTNET_EnableEventPipe : définissez cette variable sur 1 pour démarrer une session EventPipe qui écrit directement dans un fichier. La valeur par défaut est 0.

  • DOTNET_EventPipeOutputPath : chemin d’accès au fichier de trace EventPipe de sortie lorsqu’il est configuré pour s’exécuter via DOTNET_EnableEventPipe. La valeur par défaut est trace.nettrace, qui sera créée dans le même répertoire que celui à partir duquel l’application s’exécute.

    Note

    À partir de .NET 6, les instances de la chaîne {pid} dans DOTNET_EventPipeOutputPath sont remplacées par l’ID du processus en cours de suivi.

  • DOTNET_EventPipeCircularMB : valeur hexadécimale qui représente la taille de la mémoire tampon interne d’EventPipe en mégaoctets. Cette valeur de configuration est utilisée uniquement lorsque EventPipe est configuré pour s’exécuter via DOTNET_EnableEventPipe. La taille de mémoire tampon par défaut est de 1024 Mo, qui se traduit par cette variable d’environnement définie sur 400, depuis 0x400 == 1024.

    Note

    Si le processus cible écrit des événements trop fréquemment, il peut dépasser la capacité de cette mémoire tampon et certains événements peuvent être supprimés. Si trop d’événements sont supprimés, augmentez la taille de la mémoire tampon pour voir si le nombre d’événements supprimés diminue. Si le nombre d’événements supprimés ne diminue pas avec une taille de mémoire tampon plus grande, cela peut être dû à un lecteur lent empêchant le vidage des mémoires tampons du processus cible.

  • DOTNET_EventPipeProcNumbers : Réglez ceci sur 1 pour activer la capture des numéros de processeur dans les en-têtes d'événements EventPipe. La valeur par défaut est 0.

  • DOTNET_EventPipeConfig : définit la configuration de session EventPipe lors du démarrage d’une session EventPipe avec DOTNET_EnableEventPipe. La syntaxe est la suivante :

    <provider>:<keyword>:<level>

    Vous pouvez également spécifier plusieurs fournisseurs en les concaténant à l’aide d’une virgule :

    <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

    Si cette variable d’environnement n’est pas définie, mais qu’EventPipe est activé par DOTNET_EnableEventPipe, il démarre le suivi en activant les fournisseurs suivants avec les mots clés et niveaux suivants :

    • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
    • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
    • Microsoft-DotNETCore-SampleProfiler:0:5

    Pour en savoir plus sur certains fournisseurs connus dans .NET, reportez-vous aux fournisseurs d’événements connus.

  • Last updated on