Samla in och visa EventSource-spårningar

Artikel
04/08/2023

Den här artikeln gäller för: ✔️ .NET Core 3.1 och senare versioner ✔️ .NET Framework 4.5 och senare versioner

Kom igång-guiden visade hur du skapar en minimal EventSource och samlar in händelser i en spårningsfil. Den här självstudien visar hur olika verktyg kan konfigurera vilka händelser som samlas in i en spårning och sedan visa spårningarna.

Exempelapp

Du använder följande exempelapp som genererar händelser för den här självstudien. Kompilera ett .NET-konsolprogram som innehåller följande kod:

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;
        }
    }
}

Konfigurera vilka händelser som ska samlas in

De flesta verktyg för händelseinsamling använder dessa konfigurationsalternativ för att bestämma vilka händelser som ska ingå i en spårning:

Providernamn – Det här är en lista över ett eller flera EventSource-namn. Endast händelser som har definierats på EventSources i den här listan är berättigade att tas med. Om du vill samla in händelser från klassen DemoEventSource i föregående exempelapp måste du inkludera EventSource-namnet "Demo" i listan med providernamn.
Händelseveroalitetsnivå – För varje provider kan du definiera en detaljnivå och händelser med högre utförlighet än den nivån kommer att undantas från spårningen. Om du har angett att "Demo"-providern i föregående exempelapp ska samla in på informationsverig detaljnivå, kommer debugMessage-händelsen att undantas eftersom den har en högre nivå. Att EventLevel ange LogAlways(0) är ett specialfall som anger att händelser på valfri detaljnivå ska inkluderas.
Händelsenyckelord – För varje provider kan du definiera en uppsättning nyckelord och endast händelser som taggats med minst ett av nyckelorden inkluderas. Om du angav nyckelordet Start i exempelappen ovan skulle endast AppStarted- och DebugMessage-händelserna inkluderas. Om inga nyckelord anges är detta ett specialfall och innebär att händelser med ett nyckelord ska inkluderas.

Konventioner för att beskriva providerkonfiguration

Även om varje verktyg bestämmer sitt eget användargränssnitt för att ange spårningskonfigurationen finns det en vanlig konvention som många verktyg använder när du anger konfigurationen som en textsträng. Listan över providrar anges som en semikolonavgränsad lista och varje providerelement i listan består av namn, nyckelord och nivå avgränsade med kolon. Till exempel identifierar "Demo:3:5" EventSource med namnet "Demo" med nyckelordet bitmask 3 (biten Startup och biten Requests ) och EventLevel 5, som är Verbose. Med många verktyg kan du också utelämna nivån och nyckelorden om ingen nivå eller nyckelordsfiltrering önskas. Till exempel utför "Demo::5" endast nivåbaserad filtrering, "Demo:3" utför endast nyckelordsbaserad filtrering och "Demo" gör ingen nyckelords- eller nivåfiltrering.

Visual Studio

Visual Studio Profiler stöder både insamling och visning av spårningar. Den kan också visa spårningar som har samlats in i förväg av andra verktyg, till exempel dotnet-trace.

Samla in en spårning

De flesta av Visual Studio-profileringsverktygen använder fördefinierade uppsättningar händelser som har ett visst syfte, till exempel analys av CPU-användning eller allokeringar. Om du vill samla in en spårning med anpassade händelser använder du verktyget Loggboken .

Öppna Prestandaprofileraren i Visual Studio genom att välja Alt+F2.
Markera kryssrutan Loggboken .
Välj den lilla kugghjulsikonen till höger om Loggboken för att öppna konfigurationsfönstret.

I tabellen nedan Ytterligare providers lägger du till en rad för varje provider som du vill konfigurera genom att klicka på kryssrutan Aktiverad och sedan ange providernamn, nyckelord och nivå. Du behöver inte ange providerns GUID. den beräknas automatiskt.
Välj OK för att bekräfta konfigurationsinställningarna.
Välj Starta för att börja köra appen och samla in loggar.
Välj Stoppa insamling eller avsluta appen för att sluta samla in loggar och visa insamlade data.

Visa en spårning

Visual Studio kan visa spårningar som samlas in, eller visa spårningar som samlats in i andra verktyg. Om du vill visa spårningar från andra verktyg använder du Öppna fil>och väljer en spårningsfil i filväljaren. Visual Studio profiler stöder .etl-filer (ETW:s standardformat), .nettrace-filer (EventPipes standardformat) och .diagsession-filer (Visual Studios standardformat). Information om hur du arbetar med spårningsfiler i Visual Studio finns i Visual Studio-dokumentationen.

Anteckning

Visual Studio samlar in vissa händelser automatiskt från ETW eller EventPipe, även om de inte har konfigurerats uttryckligen. Om du ser händelser som du inte känner igen i kolumnen Providernamn eller Händelsenamn och vill filtrera bort dem använder du filterikonen till höger för att välja de händelser som du vill visa.

PerfView

PerfView är ett prestandaverktyg som skapats av .NET-teamet som kan samla in och visa ETW-spårningar. Den kan också visa spårningsfiler som samlats in av andra verktyg i olika format. I den här självstudien samlar du in en ETW-spårning av demoappen och undersöker sedan de insamlade händelserna i Loggboken i PerfView.

Samla in en spårning

Ladda ned PerfView från lanseringssidan. Den här självstudien gjordes med PerfView version 2.0.76, men alla senaste versioner bör fungera.
Börja PerfView.exe med administratörsbehörigheter.

Anteckning

ETW-spårningssamling kräver alltid administratörsbehörigheter, men om du bara använder PerfView för att visa en befintlig spårning behövs inga särskilda behörigheter.
På menyn Samla in väljer du Kör. Då öppnas en ny dialogruta där du anger sökvägen till demoappen.
Om du vill konfigurera vilka händelser som samlas in expanderar du Avancerade alternativ längst ned i dialogrutan. I textrutan Ytterligare providers anger du providers med det konventionella textformat som beskrevs tidigare. I det här fallet anger du "Demo:1:4", vilket innebär nyckelord bit 1 (Startup händelser) och verbositet 4 (Informational).
Om du vill starta appen och börja samla in spårningen väljer du knappen Kör kommando . När appen avslutas sparas spårningen PerfViewData.etl i den aktuella katalogen.

Visa en spårning

I den nedrullningsbara textrutan i huvudfönstret längst upp till vänster väljer du katalogen som innehåller spårningsfilen. Dubbelklicka sedan på spårningsfilen i trädvyn nedan.
Om du vill öppna Loggboken dubbelklickar du på objektet Händelser som visas i trädvyn under spårningsfilen.
Alla händelsetyper i spårningen visas i listan till vänster. Dubbelklicka på en händelsetyp, till exempel Demo\AppStarted, för att visa alla händelser av den typen i tabellen till höger.

Läs mer

Mer information om hur du använder PerfView finns i självstudierna om PerfView-video.

dotnet-trace

dotnet-trace är ett plattformsoberoende kommandoradsverktyg som kan samla in spårningar från .NET Core-appar med hjälp av EventPipe-spårning . Det stöder inte visning av spårningsdata, men de spårningar som samlas in kan visas av andra verktyg som PerfView eller Visual Studio. dotnet-trace stöder också konvertering av standardspårningar i .nettrace-format till andra format, till exempel Chromium eller Speedscope.

Samla in en spårning

Ladda ned och installera dotnet-trace.

Kör kommandot dotnet-trace collect på kommandoraden:

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

Detta bör visa utdata som liknar:

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 använder det konventionella textformatet för att beskriva providerkonfigurationen --providers i argumentet . Fler alternativ för hur du tar spårningar med dotnet-trace finns i dotnet-trace-dokumenten.

EventListener

System.Diagnostics.Tracing.EventListener är ett .NET-API som kan användas från pågående för att ta emot återanrop för händelser som genereras av en System.Diagnostics.Tracing.EventSource. Det här API:et kan användas för att skapa anpassade loggningsverktyg eller för att analysera händelserna i minnet utan att serialisera dem.

Om du vill använda EventListenerdeklarerar du en typ som härleds från EventListener, anropar EnableEvents för att prenumerera på händelser från valfri EventSource av intresse och åsidosätter OnEventWritten, som anropas när en ny händelse är tillgänglig. Det är ofta användbart att åsidosätta OnEventSourceCreated för att identifiera vilka EventSource-objekt som finns, men detta krävs inte. Följande är ett exempel på EventListener en implementering som skriver ut till konsolen när meddelanden tas emot:

Lägg till den här koden i demoappen.

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);
    }
}

Main Ändra metoden för att skapa en instans av den nya lyssnaren.

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);
}

Kompilera och kör appen. Tidigare hade den inga utdata, men nu skriver den händelserna till konsolen:
```
3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop
```

Dela via

Samla in och visa EventSource-spårningar

Exempelapp

Konfigurera vilka händelser som ska samlas in

Konventioner för att beskriva providerkonfiguration

Visual Studio

Samla in en spårning

Visa en spårning

PerfView

Samla in en spårning

Visa en spårning

Läs mer

dotnet-trace

Samla in en spårning

EventListener

Ytterligare resurser