EventSource-traceringen verzamelen en weergeven

Dit artikel is van toepassing op: ✔️ .NET Core 3.1 en latere versies ✔️ .NET Framework 4.5 en latere versies

In de handleiding Aan de slag hebt u laten zien hoe u een minimale EventSource maakt en gebeurtenissen in een traceringsbestand verzamelt. In deze zelfstudie ziet u hoe verschillende hulpprogramma's kunnen configureren welke gebeurtenissen in een trace worden verzameld en vervolgens de traceringen kunnen weergeven.

Voorbeeld-app

U gebruikt de volgende voorbeeld-app waarmee gebeurtenissen voor deze zelfstudie worden gegenereerd. Compileer een .NET-consoletoepassing met de volgende code:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Configureren welke gebeurtenissen moeten worden verzameld

De meeste hulpprogramma's voor gebeurtenisverzameling gebruiken deze configuratieopties om te bepalen welke gebeurtenissen moeten worden opgenomen in een tracering:

• Providernamen: dit is een lijst met een of meer EventSource-namen. Alleen gebeurtenissen die zijn gedefinieerd voor EventSources in deze lijst komen in aanmerking om te worden opgenomen. Als u gebeurtenissen uit de klasse DemoEventSource in de voorgaande voorbeeld-app wilt verzamelen, moet u de EventSource-naam 'Demo' opnemen in de lijst met providernamen.
• Uitgebreidheidsniveau van gebeurtenissen: voor elke provider kunt u een uitgebreidheidsniveau definiëren en gebeurtenissen met uitgebreidheid hoger dan dat niveau worden uitgesloten van de tracering. Als u hebt opgegeven dat de provider Demo in de voorgaande voorbeeld-app moet verzamelen op het uitgebreidheidsniveau Informatie, wordt de gebeurtenis DebugMessage uitgesloten omdat deze een hoger niveau heeft. EventLevel LogAlways(0) opgeven is een speciaal geval dat aangeeft dat gebeurtenissen met een uitgebreidheidsniveau moeten worden opgenomen.
• Trefwoorden voor gebeurtenissen: voor elke provider kunt u een set trefwoorden definiëren. Alleen gebeurtenissen met een label met ten minste één van de trefwoorden worden opgenomen. Als u in de bovenstaande voorbeeld-app het trefwoord Opstarten hebt opgegeven, worden alleen de gebeurtenissen AppStarted en DebugMessage opgenomen. Als er geen trefwoorden worden opgegeven, is dit een speciaal geval en betekent dit dat gebeurtenissen met een willekeurig trefwoord moeten worden opgenomen.

Conventies voor het beschrijven van providerconfiguratie

Hoewel elk hulpprogramma een eigen gebruikersinterface bepaalt voor het instellen van de traceringsconfiguratie, is er een algemene conventie die veel hulpprogramma's gebruiken bij het opgeven van de configuratie als een tekenreeks. De lijst met providers wordt opgegeven als een door puntkomma's gescheiden lijst en elk providerelement in de lijst bestaat uit naam, trefwoorden en niveau, gescheiden door dubbele punten. 'Demo:3:5' identificeert bijvoorbeeld de gebeurtenisbron met de naam 'Demo' met het trefwoord bitmasker 3 (de Startup bit en de Requests bit) en EventLevel 5, wat is Verbose. In veel hulpprogramma's kunt u ook het niveau en de trefwoorden weglaten als u geen niveau of trefwoordfilter wilt filteren. 'Demo::5' doet bijvoorbeeld alleen filteren op niveau, 'Demo:3' alleen filteren op trefwoorden en 'Demo' doet geen filters voor trefwoorden of niveaufilters.

Visual Studio

De Visual Studio Profiler ondersteunt het verzamelen en weergeven van traceringen. Het kan ook traceringen weergeven die vooraf zijn verzameld door andere hulpprogramma's, zoals dotnet-trace.

Een tracering verzamelen

De meeste profileringshulpprogramma's van Visual Studio maken gebruik van vooraf gedefinieerde sets gebeurtenissen die een bepaald doel dienen, zoals het analyseren van CPU-gebruik of toewijzingen. Als u een tracering met aangepaste gebeurtenissen wilt verzamelen, gebruikt u het hulpprogramma Gebeurtenissenviewer .

1. Selecteer Alt+F2 om de Performance Profiler in Visual Studio te openen.

2. Schakel het selectievakje Logboeken in .

   

3. Selecteer het kleine tandwielpictogram rechts van Gebeurtenisviewer om het configuratievenster te openen.

   Voeg in de onderstaande tabel Extra providers een rij toe voor elke provider die u wilt configureren door op het selectievakje Ingeschakeld te klikken en vervolgens de naam, trefwoorden en niveau van de provider in te voeren. U hoeft de provider-GUID niet in te voeren; het wordt automatisch berekend.

   

4. Selecteer OK om de configuratie-instellingen te bevestigen.

5. Selecteer Start om de app uit te voeren en logboeken te verzamelen.

6. Selecteer Verzameling stoppen of sluit de app af om het verzamelen van logboeken te stoppen en de verzamelde gegevens weer te geven.

Een tracering weergeven

Visual Studio kan traceringen bekijken die het zelf heeft verzameld, of traceringen weergeven die zijn verzameld in andere hulpprogramma's. Als u traceringen van andere hulpprogramma's wilt weergeven, gebruikt u Bestand>openen en selecteert u een traceringsbestand in de bestandskiezer. Visual Studio Profiler ondersteunt ETL-bestanden (de standaardindeling van ETW), .nettrace-bestanden (de standaardindeling van EventPipe) en .diagsession-bestanden (de standaardindeling van Visual Studio). Zie de Visual Studio-documentatie voor informatie over het werken met traceringsbestanden in Visual Studio.

Notitie

Visual Studio verzamelt sommige gebeurtenissen automatisch van ETW of EventPipe, zelfs als ze niet expliciet zijn geconfigureerd. Als u gebeurtenissen ziet die u niet herkent in de kolom Providernaam of Gebeurtenisnaam en u deze wilt uitfilteren, gebruikt u het filterpictogram aan de rechterkant om alleen de gebeurtenissen te selecteren die u wilt weergeven.

PerfView

PerfView is een prestatiehulpprogramma dat is gemaakt door het .NET-team dat ETW-traceringen kan verzamelen en weergeven. Het kan ook traceringsbestanden weergeven die zijn verzameld door andere hulpprogramma's in verschillende indelingen. In deze zelfstudie verzamelt u een ETW-tracering van de demo-app en bekijkt u vervolgens de verzamelde gebeurtenissen in de logboekenviewer van PerfView.

Een tracering verzamelen

1. Download PerfView op de pagina releases. Deze zelfstudie is uitgevoerd met PerfView versie 2.0.76, maar elke recente versie zou moeten werken.

2. Start PerfView.exe met beheerdersmachtigingen.

   Notitie

   Voor etw-traceringsverzameling zijn altijd beheerdersmachtigingen vereist. Als u echter alleen PerfView gebruikt om een bestaande tracering weer te geven, zijn er geen speciale machtigingen nodig.

   

3. Selecteer Uitvoeren in het menu Verzamelen. Hiermee opent u een nieuw dialoogvenster waarin u het pad naar de demo-app invoert.

   

4. Als u wilt configureren welke gebeurtenissen worden verzameld, vouwt u Geavanceerde opties onder aan het dialoogvenster uit. Voer in het tekstvak Aanvullende providers providers in met de conventionele tekstindeling die eerder is beschreven. In dit geval voert u 'Demo:1:4' in, wat betekent dat trefwoord bit 1 (Startup gebeurtenissen) en uitgebreidheid 4 (Informational) betekent.

   

5. Als u de app wilt starten en de tracering wilt verzamelen, selecteert u de knop Opdracht uitvoeren . Wanneer de app wordt afgesloten, wordt de tracering PerfViewData.etl opgeslagen in de huidige map.

Een tracering weergeven

1. Selecteer in de vervolgkeuzelijst van het hoofdvenster linksboven de map met het traceringsbestand. Dubbelklik vervolgens op het traceringsbestand in de structuurweergave hieronder.

   

2. Als u de gebeurtenisviewer wilt weergeven, dubbelklikt u op het item Gebeurtenissen dat wordt weergegeven in de structuurweergave onder het traceringsbestand.

   

3. Alle gebeurtenistypen in de tracering worden weergegeven in de lijst aan de linkerkant. Dubbelklik op een gebeurtenistype, zoals Demo\AppStarted, om alle gebeurtenissen van dat type weer te geven in de tabel aan de rechterkant.

   

Lees meer

Zie de PerfView-videozelfstudies voor meer informatie over het gebruik van PerfView.

dotnet-trace

dotnet-trace is een platformoverschrijdend opdrachtregelprogramma waarmee traceringen van .NET Core-apps kunnen worden verzameld met behulp van EventPipe-tracering . Het biedt geen ondersteuning voor het weergeven van traceringsgegevens, maar de traceringen die worden verzameld, kunnen worden bekeken door andere hulpprogramma's, zoals PerfView of Visual Studio. dotnet-trace ondersteunt ook het converteren van de standaard .nettrace-indelingstrace-traceringen naar andere indelingen, zoals Chromium of Speedscope.

Een tracering verzamelen

1. Download en installeer dotnet-trace.

2. Voer op de opdrachtregel de opdracht dotnet-trace collect uit :

   E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   

   De uitvoer moet er ongeveer als volgt uitzien:

   E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   
   Provider Name                           Keywords            Level               Enabled By
   Demo                                    0x0000000000000001  Informational(4)    --providers
   
   Launching: EventSourceDemo.exe
   Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
   Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220317_021512.nettrace
   
   [00:00:00:00]   Recording trace 0.00     (B)
   Press <Enter> or <Ctrl+C> to exit...
   
   Trace completed.
   

   dotnet-trace gebruikt de conventionele tekstindeling voor het beschrijven van de providerconfiguratie in het --providers argument. Zie de dotnet-trace-docs voor meer opties voor het nemen van traceringen met behulp van dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener is een .NET-API die kan worden gebruikt vanuit een proces om callbacks te ontvangen voor gebeurtenissen die worden gegenereerd door een System.Diagnostics.Tracing.EventSource. Deze API kan worden gebruikt om aangepaste hulpprogramma's voor logboekregistratie te maken of om de gebeurtenissen in het geheugen te analyseren zonder ze ooit te serialiseren.

Als u wilt gebruiken EventListener, declareert u een type dat is afgeleid van EventListener, roept EnableEvents u aan om u te abonneren op de gebeurtenissen van een eventsource van belang en overschrijft u de OnEventWritten, die wordt aangeroepen wanneer er een nieuwe gebeurtenis beschikbaar is. Het is vaak handig om te overschrijven OnEventSourceCreated om te ontdekken welke EventSource-objecten bestaan, maar dit is niet vereist. Hier volgt een voorbeeld EventListener van een implementatie die wordt afgedrukt naar de console wanneer berichten worden ontvangen:

1. Voeg deze code toe aan de demo-app.

   class ConsoleWriterEventListener : EventListener
   {
       protected override void OnEventSourceCreated(EventSource eventSource)
       {
           if(eventSource.Name == "Demo")
           {
               EnableEvents(eventSource, EventLevel.Informational);
           }
       }
   
       protected override void OnEventWritten(EventWrittenEventArgs eventData)
       {
           Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
       }
   }
   

2. Wijzig de Main methode om een exemplaar van de nieuwe listener te maken.

   public static void Main(string[] args)
   {
       ConsoleWriterEventListener listener = new ConsoleWriterEventListener();
   
       DemoEventSource.Log.AppStarted("Hello World!", 12);
       DemoEventSource.Log.DebugMessage("Got here");
       DemoEventSource.Log.DebugMessage("finishing startup");
       DemoEventSource.Log.RequestStart(3);
       DemoEventSource.Log.RequestStop(3);
   }
   

3. Bouw de app en voer deze uit. Voorheen had het geen uitvoer, maar nu worden de gebeurtenissen naar de console geschreven:

   3/24/2022 9:23:35 AM AppStarted
   3/24/2022 9:23:35 AM RequestStart
   3/24/2022 9:23:35 AM RequestStop