Komma igång med EventSource
Den här artikeln gäller för: ✔️ .NET Core 3.1 och senare versioner ✔️ .NET Framework 4.5 och senare versioner
Den här genomgången visar hur du loggar en ny händelse med System.Diagnostics.Tracing.EventSource, samlar in händelser i en spårningsfil, visar spårningen och förstår grundläggande EventSource-begrepp.
Not
Många tekniker som integreras med EventSource använder termerna "Spårning" och "Spårningar" i stället för "Loggning" och "Loggar". Innebörden är densamma här.
Logga en händelse
Målet med EventSource är att tillåta .NET-utvecklare att skriva kod som den här för att logga en händelse:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Den här kodraden har ett loggningsobjekt (DemoEventSource.Log), en metod som representerar händelsen för att logga (AppStarted), och eventuellt några starkt skrivna händelseparametrar (HelloWorld! och 12). Det finns inga utförliga nivåer, händelse-ID:n, meddelandemallar eller något annat som inte behöver finnas på samtalswebbplatsen. All den här andra informationen om händelser skrivs genom att definiera en ny klass som härleds från System.Diagnostics.Tracing.EventSource.
Här är ett fullständigt minimalt exempel:
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);
}
}
Klassen DemoEventSource deklarerar en metod för varje typ av händelse som du vill logga. I det här fallet definieras en enskild händelse med namnet "AppStarted" av metoden AppStarted(). Varje gång koden anropar AppStarted-metoden registreras en annan AppStarted-händelse i spårningen om händelsen är aktiverad. Det här är några av de data som kan samlas in med varje händelse:
- Händelsenamn – ett namn som identifierar den typ av händelse som loggades. Händelsenamnet är identiskt med metodnamnet AppStarted i det här fallet.
- Händelse-ID – ett numeriskt ID som identifierar den typ av händelse som loggades. Detta fungerar ungefär som namnet men kan hjälpa till med snabb automatiserad loggbearbetning. Händelsen AppStarted har ett ID på 1 som anges i EventAttribute.
- Källnamn – namnet på den EventSource som innehåller händelsen. Detta används som ett namnområde för händelser. Händelsenamn och ID:n behöver bara vara unika inom källans omfång. Här heter källan "Demo", som anges i EventSourceAttribute i klassdefinitionen. Källnamnet kallas också ofta för ett providernamn.
- Argument – Alla metodargumentvärden serialiseras.
- Annan information – Händelser kan också innehålla tidsstämplar, tråd-ID:n, processor-ID:n, aktivitets-ID:n, stackspårningar och händelsemetadata som meddelandemallar, utförlighetsnivåer och nyckelord.
Mer information och metodtips för att skapa händelser finns i Instrumenteringskod för att skapa händelser.
Samla in och visa en spårningsfil
Det finns ingen nödvändig konfiguration i koden som beskriver vilka händelser som ska aktiveras, var loggade data ska skickas eller vilket format data ska lagras i. Om du kör appen nu skapas ingen spårningsfil som standard. EventSource använder publish-subscribe-mönstret, som kräver att prenumeranter anger vilka händelser som ska aktiveras och för att kontrollera all serialisering för de prenumererade händelserna. EventSource har integrationer för att prenumerera från Event Tracing för Windows (ETW) och EventPipe (endast .NET Core). Anpassade prenumeranter kan också skapas med hjälp av api:et System.Diagnostics.Tracing.EventListener.
Den här demonstrationen visar ett EventPipe- exempel för .NET Core-appar. Mer information om fler alternativ finns i Samla in och visa händelsespårningar. EventPipe är en öppen och plattformsoberoende spårningsteknik som är inbyggd i .NET Core-körningen för att ge .NET-utvecklare verktyg för spårningsinsamling och ett portabelt kompakt spårningsformat (*.nettrace-filer). dotnet-trace är ett kommandoradsverktyg som samlar in EventPipe-spårningar.
- Ladda ned och installera dotnet-trace.
- Skapa konsolappen ovan. Den här demonstrationen förutsätter att appen heter EventSourceDemo.exe och att den finns i den aktuella katalogen. Vid kommandoradskörningen:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
Detta bör visa utdata som liknar:
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.
Det här kommandot körde EventSourceDemo.exe med alla händelser i "Demo" EventSource aktiverat och genererade spårningsfilen EventSourceDemo.exe_20220303_001619.nettrace.
När du öppnar filen i Visual Studio visas de händelser som loggades.
I listvyn kan du se att den första händelsen är Demo/AppStarted-händelsen. Textkolumnen har de sparade argumenten, tidsstämpelkolumnen visar händelsen inträffade 27 ms efter att loggningen startade och till höger kan du se anropsstacken. De andra händelserna aktiveras automatiskt i varje spårning som samlas in av dotnet-trace, även om de kan ignoreras och filtreras från vyn i användargränssnittet om de distraherar. Dessa extra händelser samlar in viss information om processen och jitted-koden, vilket gör att Visual Studio kan rekonstruera händelsestackens spårningar.
