Aan de slag met EventSource

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

In deze procedure ziet u hoe u een nieuwe gebeurtenis kunt registreren met System.Diagnostics.Tracing.EventSource, gebeurtenissen kunt verzamelen in een traceringsbestand, hoe u de tracering kunt bekijken en hoe u de basisconcepten van EventSource begrijpt.

Notitie

Veel technologieën die zijn geïntegreerd met EventSource gebruiken de termen Tracering en Traceringen in plaats van 'Logboekregistratie' en 'Logboeken'. De betekenis is hier hetzelfde.

Een gebeurtenis registreren

Het doel van EventSource is om .NET-ontwikkelaars in staat te stellen code zoals deze te schrijven om een gebeurtenis te registreren:

DemoEventSource.Log.AppStarted("Hello World!", 12);

Deze coderegel heeft een logboekobject (DemoEventSource.Log), een methode die de gebeurtenis aangeeft die moet worden vastgelegd (AppStarted) en eventueel enkele sterk getypte gebeurtenisparameters (HelloWorld! en 12). Er zijn geen uitbreidingsniveaus, gebeurtenis-id's, berichtsjablonen of iets anders dat niet op de oproepsite hoeft te staan. Al deze andere informatie over gebeurtenissen wordt geschreven door een nieuwe klasse te definiëren die is afgeleid van System.Diagnostics.Tracing.EventSource.

Hier volgt een volledig minimaal voorbeeld:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
        }
    }

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

        [Event(1)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
    }
}

De klasse DemoEventSource declareert een methode voor elk type gebeurtenis dat u wilt registreren. In dit geval wordt één gebeurtenis met de naam 'AppStarted' gedefinieerd door de methode AppStarted(). Telkens wanneer de code de AppStarted-methode aanroept, wordt er een andere AppStarted-gebeurtenis vastgelegd in de trace als de gebeurtenis is ingeschakeld. Dit zijn enkele van de gegevens die met elke gebeurtenis kunnen worden vastgelegd:

• Gebeurtenisnaam: een naam die het type gebeurtenis aangeeft dat is geregistreerd. De gebeurtenisnaam is in dit geval identiek aan de naam van de methode, 'AppStarted'.
• Gebeurtenis-id: een numerieke id die het type gebeurtenis identificeert dat is geregistreerd. Dit heeft een vergelijkbare rol als de naam, maar kan helpen bij snelle geautomatiseerde logboekverwerking. De gebeurtenis AppStarted heeft een id van 1, opgegeven in de EventAttribute.
• Bronnaam: de naam van de EventSource die de gebeurtenis bevat. Dit wordt gebruikt als een naamruimte voor gebeurtenissen. Gebeurtenisnamen en id's hoeven alleen uniek te zijn binnen het bereik van hun bron. Hier heeft de bron de naam Demo, die is opgegeven in de EventSourceAttribute klassedefinitie. De bronnaam wordt ook wel een providernaam genoemd.
• Argumenten: alle argumentwaarden van de methode worden geserialiseerd.
• Andere informatie: gebeurtenissen kunnen ook tijdstempels, thread-id's, processor-id's, activiteit-id's, stacktraceringen en gebeurtenismetagegevens bevatten, zoals berichtsjablonen, uitgebreidheidsniveaus en trefwoorden.

Zie Instrumenting-code voor het maken van gebeurtenissen voor meer informatie en aanbevolen procedures voor het maken van gebeurtenissen.

Een traceringsbestand verzamelen en weergeven

Er is geen vereiste configuratie in code waarin wordt beschreven in welke gebeurtenissen moeten worden ingeschakeld, waarin de vastgelegde gegevens moeten worden verzonden of in welke indeling de gegevens moeten worden opgeslagen. Als u de app nu uitvoert, wordt er standaard geen traceringsbestand geproduceerd. EventSource maakt gebruik van het patroon Publish-subscribe, waarvoor abonnees de gebeurtenissen moeten aangeven die moeten worden ingeschakeld en om alle serialisatie voor de geabonneerde gebeurtenissen te beheren. EventSource heeft integraties voor het abonneren vanaf Event Tracing voor Windows (ETW) en EventPipe (alleen.NET Core). Aangepaste abonnees kunnen ook worden gemaakt met behulp van de System.Diagnostics.Tracing.EventListener API.

In deze demo ziet u een EventPipe-voorbeeld voor .NET Core-apps. Zie Gebeurtenistraceringen verzamelen en weergeven voor meer informatie over meer opties. EventPipe is een open en platformoverschrijdende traceringstechnologie die is ingebouwd in de .NET Core-runtime om .NET-ontwikkelaars traceringshulpprogramma's en een draagbare compacte traceringsindeling (*.nettrace-bestanden) te bieden. dotnet-trace is een opdrachtregelprogramma waarmee EventPipe-traceringen worden verzameld.

1. Dotnet-trace downloaden en installeren
2. Bouw de bovenstaande console-app. In deze demo wordt ervan uitgegaan dat de app de naam EventSourceDemo.exe heeft en zich in de huidige map bevindt. Voer tijdens de opdrachtregel het volgende uit:

>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

Dit moet uitvoer weergeven die vergelijkbaar is met:

Provider Name                           Keywords            Level               Enabled By
Demo                                    0xFFFFFFFFFFFFFFFF  Verbose(5)          --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_20220303_001619.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

Met deze opdracht is EventSourceDemo.exe uitgevoerd met alle gebeurtenissen in de EventSource Demo ingeschakeld en wordt het traceringsbestand EventSourceDemo.exe_20220303_001619.nettraceuitgevoerd. Als u het bestand opent in Visual Studio, worden de gebeurtenissen weergegeven die zijn vastgelegd.

In de lijstweergave ziet u dat de eerste gebeurtenis de demo-/AppStarted-gebeurtenis is. De tekstkolom heeft de opgeslagen argumenten, de tijdstempelkolom toont de gebeurtenis 27 ms nadat de logboekregistratie is gestart en rechts ziet u de callstack. De andere gebeurtenissen worden automatisch ingeschakeld in elke trace die wordt verzameld door dotnet-trace, hoewel ze kunnen worden genegeerd en gefilterd vanuit de weergave in de gebruikersinterface als ze afleiden. Deze extra gebeurtenissen leggen informatie vast over het proces en de jitted code, waardoor Visual Studio de traceringen van de gebeurtenisstack kan reconstrueren.

Meer informatie over EventSource

• Instrumentatiecode voor het maken van gebeurtenissen
• Gebeurtenistraceringen verzamelen en weergeven