Delen via

EventPipe

  • Artikel

EventPipe is een runtime-onderdeel dat kan worden gebruikt voor het verzamelen van traceringsgegevens, vergelijkbaar met ETW of perf_events. Het doel van EventPipe is om .NET-ontwikkelaars in staat te stellen hun .NET-toepassingen eenvoudig te traceren zonder dat ze hoeven te vertrouwen op platformspecifieke onderdelen met hoge bevoegdheden, zoals ETW of perf_events.

EventPipe is het mechanisme achter veel diagnostische hulpprogramma's en kan worden gebruikt voor het verbruik van gebeurtenissen die door de runtime worden verzonden, evenals aangepaste gebeurtenissen die zijn geschreven met EventSource.

Dit artikel is een algemeen overzicht van EventPipe. Hierin wordt beschreven wanneer en hoe u EventPipe gebruikt en hoe u deze zo configureert dat deze het beste bij uw behoeften past.

Basisprincipes van EventPipe

EventPipe aggregert gebeurtenissen die worden verzonden door runtime-onderdelen, bijvoorbeeld de Just-In-Time-compiler of de garbagecollector, en gebeurtenissen die zijn geschreven uit EventSource-exemplaren in de bibliotheken en gebruikerscode.

De gebeurtenissen worden vervolgens geserialiseerd in de .nettrace bestandsindeling en kunnen rechtstreeks naar een bestand worden geschreven of via een diagnostische poort worden gestreamd voor out-of-process consumption.

Raadpleeg de documentatie over de EventPipe-indeling voor meer informatie over de Serialisatie-indeling van EventPipe.

EventPipe versus ETW/perf_events

EventPipe maakt deel uit van de .NET-runtime en is ontworpen om op dezelfde manier te werken op alle platforms die .NET Core ondersteunt. Hierdoor kunnen traceringshulpprogramma's op basis van EventPipe, zoals dotnet-counters, dotnet-gcdumpen dotnet-trace, naadloos op verschillende platforms worden uitgevoerd.

Omdat EventPipe echter een ingebouwd runtime-onderdeel is, is het bereik beperkt tot beheerde code en de runtime zelf. EventPipe-gebeurtenissen bevatten alleen stacktraces met informatie over het beheerde codeframe. Als u gebeurtenissen wilt genereren op basis van andere niet-beheerde bibliotheken in de gebruikersmodus, CPU-steekproeven voor systeemeigen code of kernelgebeurtenissen, moet u hulpprogramma's voor het traceren van het besturingssysteem gebruiken, zoals ETW of perf_events. In Linux helpt het hulpprogramma perfcollect bij het automatiseren van het gebruik van perf_events en LTTng.

Een ander belangrijk verschil tussen EventPipe en ETW/perf_events is vereiste voor beheerders-/hoofdbevoegdheden. Als u een toepassing wilt traceren met ETW of perf_events moet u een beheerder/hoofdmap zijn. Met EventPipe kunt u toepassingen traceren zolang de tracer (bijvoorbeeld dotnet-trace) wordt uitgevoerd als dezelfde gebruiker als de gebruiker die de toepassing heeft gestart.

De volgende tabel is een samenvatting van de verschillen tussen EventPipe en ETW/perf_events.

Functie EventPipe ETW perf_events
Platformonafhankelijk Ja Nee (alleen in Windows) Nee (alleen op ondersteunde Linux-distributies)
Beheerders-/hoofdmachtiging vereisen Nr. Ja Ja
Kan gebeurtenissen van het besturingssysteem/de kernel ophalen Nr. Ja Ja
Kan systeemeigen callstacks oplossen Nr. Ja Ja

EventPipe gebruiken om uw .NET-toepassing te traceren

U kunt EventPipe gebruiken om uw .NET-toepassing op veel manieren te traceren:

Nadat u een nettrace bestand hebt gemaakt dat uw EventPipe-gebeurtenissen bevat, kunt u het bestand weergeven in PerfView of Visual Studio. Op niet-Windows-platforms kunt u het nettrace bestand converteren naar een speedscope of Chromium traceringsindeling met behulp van de opdracht dotnet-trace convert en het weergeven met speedscope of Chrome DevTools.

U kunt EventPipe-traceringen ook programmatisch analyseren met TraceEvent.

Hulpprogramma's die EventPipe gebruiken

Dit is de eenvoudigste manier om EventPipe te gebruiken om uw toepassing te traceren. Raadpleeg de documentatie van elk hulpprogramma voor meer informatie over het gebruik van deze hulpprogramma's.

  • Met dotnet-counters kunt u verschillende metrische gegevens bewaken en verzamelen die worden verzonden door de .NET-runtime- en kernbibliotheken, evenals aangepaste metrische gegevens die u kunt schrijven.

  • met dotnet-gcdump kunt u GC-heapdumps van liveprocessen verzamelen voor het analyseren van de beheerde heap van een toepassing.

  • met dotnet-trace kunt u traceringen van toepassingen verzamelen die moeten worden geanalyseerd op prestaties.

Traceren met behulp van omgevingsvariabelen

Het voorkeursmechanisme voor het gebruik van EventPipe is het gebruik van dotnet-trace of de Microsoft.Diagnostics.NETCore.Client-bibliotheek .

U kunt echter de volgende omgevingsvariabelen gebruiken om een EventPipe-sessie in een app in te stellen en deze rechtstreeks naar een bestand te laten schrijven. Sluit de toepassing af om het traceren te stoppen.

  • DOTNET_EnableEventPipe: Stel dit in om 1 een EventPipe-sessie te starten die rechtstreeks naar een bestand schrijft. De standaardwaarde is 0.

  • DOTNET_EventPipeOutputPath: Het pad naar het uitvoer-EventPipe-traceringsbestand wanneer het is geconfigureerd om te worden uitgevoerd via DOTNET_EnableEventPipe. De standaardwaarde is trace.nettrace, die wordt gemaakt in dezelfde map waaruit de app wordt uitgevoerd.

    Notitie

    Sinds .NET 6 worden exemplaren van de tekenreeks {pid} DOTNET_EventPipeOutputPath vervangen door de proces-id van het proces dat wordt getraceerd.

  • DOTNET_EventPipeCircularMB: Een hexadecimale waarde die de grootte van de interne buffer van EventPipe in megabytes vertegenwoordigt. Deze configuratiewaarde wordt alleen gebruikt wanneer EventPipe is geconfigureerd voor uitvoering via DOTNET_EnableEventPipe. De standaardbuffergrootte is 1024 MB die wordt omgezet in deze omgevingsvariabele die wordt ingesteld op 400, sinds == 0x4001024 .

    Notitie

    Als het doelproces gebeurtenissen te vaak schrijft, kan deze buffer overlopen en kunnen sommige gebeurtenissen worden verwijderd. Als er te veel gebeurtenissen worden verwijderd, vergroot u de buffergrootte om te zien of het aantal verwijderde gebeurtenissen vermindert. Als het aantal verwijderde gebeurtenissen niet afneemt met een grotere buffergrootte, kan dit worden veroorzaakt door een trage lezer die verhindert dat de buffers van het doelproces worden leeggemaakt.

  • DOTNET_EventPipeProcNumbers: Stel dit in om 1 het vastleggen van processornummers in EventPipe-gebeurtenisheaders in te schakelen. De standaardwaarde is 0.

  • DOTNET_EventPipeConfig: Hiermee stelt u de EventPipe-sessieconfiguratie in bij het starten van een EventPipe-sessie met DOTNET_EnableEventPipe. De syntaxis is als volgt:

    <provider>:<keyword>:<level>

    U kunt ook meerdere providers opgeven door ze samen te stellen met een komma:

    <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

    Als deze omgevingsvariabele niet is ingesteld, maar EventPipe is ingeschakeld DOTNET_EnableEventPipe, wordt de tracering gestart door de volgende providers in te schakelen met de volgende trefwoorden en niveaus:

    • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
    • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
    • Microsoft-DotNETCore-SampleProfiler:0:5

    Raadpleeg bekende gebeurtenisproviders voor meer informatie over enkele bekende providers in .NET.

Notitie

.NET 6 standaardiseert het voorvoegsel DOTNET_ in plaats van COMPlus_ voor omgevingsvariabelen die .NET-runtimegedrag configureren. COMPlus_ Het voorvoegsel blijft echter werken. Als u een eerdere versie van de .NET-runtime gebruikt, moet u nog steeds het COMPlus_ voorvoegsel voor omgevingsvariabelen gebruiken.