Delen via

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 verzamelt in een traceringsbestand, hoe u de tracering kunt bekijken en basisconcepten van EventSource kunt begrijpen.

Notitie

Veel technologieën die met EventSource integreren, gebruiken de termen 'tracering' en 'traces' 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 vertegenwoordigt die moet worden vastgelegd (AppStarted), en eventueel enkele sterk getypte gebeurtenisparameters (HelloWorld! en 12). Er zijn geen niveaus van detaillering, gebeurtenis-ID's, berichtsjablonen of iets anders dat niet op de aanroepplaats 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 AppStarted-gebeurtenis 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 van de 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, niveaus van gedetailleerdheid en trefwoorden.

Zie Instrumenting-code voor het maken van gebeurtenissenvoor meer informatie en best practices voor het maken van gebeurtenissen.

Een traceringsbestand verzamelen en weergeven

Er is geen vereiste configuratie in code die beschrijft welke gebeurtenissen moeten worden ingeschakeld, waarheen 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. Hiervoor moeten abonnees aangeven welke gebeurtenissen moeten worden ingeschakeld en om alle serialisatie voor de geabonneerde gebeurtenissen te beheren. EventSource heeft integraties voor het abonneren op Event Tracing for 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 weergevenvoor 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 commandoregelprogramma dat EventPipe-traceringen verzamelt.

  1. Download en installeer dotnet-trace.
  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 'Demo' EventSource ingeschakeld, en het traceringsbestand EventSourceDemo.exe_20220303_001619.nettracewordt aangemaakt. Als u het bestand opent in Visual Studio, worden de gebeurtenissen weergegeven die zijn vastgelegd.

Nettrace-bestand van Visual Studio

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, maar ze kunnen worden genegeerd en uit de weergave gefilterd 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