Delen via

hulpprogramma voor prestatieanalyse van dotnet-trace

Dit artikel is van toepassing op: ✔️ dotnet-trace 9.0.661903 en latere versies

Installeren

Er zijn twee manieren om te downloaden en installeren dotnet-trace:

Samenvatting

dotnet-trace [-h, --help] [--version] <command>

Beschrijving

Het dotnet-trace hulpprogramma:

  • Is een platformoverschrijdend .NET Core-hulpprogramma.

  • Hiermee kunt u .NET Core-traceringen van een actief proces zonder systeemeigen profiler verzamelen.

  • Is gebaseerd op EventPipe de .NET Core-runtime.

  • Ondersteunt twee verschillende manieren om traceringen te verzamelen:

    • Het collect werkwoord biedt consistente functionaliteit voor elk besturingssysteem.
    • Het collect-linux werkwoord maakt gebruik van linux-specifieke besturingssysteemmogelijkheden om extra functies te bieden.
    Characteristic collect collect-linux
    Ondersteund besturingssysteem Welke dan ook Alleen Linux, kernelversie >= 6.4
    Beheerders-/hoofdmachtiging vereist Nee. Yes
    Alle processen tegelijk traceren Nee. Ondersteund
    Systeemeigen bibliotheek- en kernel-gebeurtenissen vastleggen Nee. Ondersteund
    Event callstacks bevatten systeemeigen frames Nee. Yes

Opties

  • -h|--help

    Toont opdrachtregelhulp.

  • --version

    Geeft de versie van het hulpprogramma dotnet-trace weer.

Opdracht

Opdracht
dotnet-trace collect
dotnet-trace collect-linux
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace-rapport

dotnet-trace collect

Verzamelt een diagnostische tracering van een actief proces of start een onderliggend proces en traceert het (.NET 5 of hoger). Als u wilt dat het hulpprogramma een onderliggend proces uitvoert en deze traceert vanaf het opstarten, voegt u de opdracht Verzamelen toe -- .

Samenvatting

dotnet-trace collect
    [--buffersize <size>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--dsrouter <ios|ios-sim|android|android-emu>]
    [--format <Chromium|NetTrace|Speedscope>]
    [-h|--help]
    [--duration dd:hh:mm:ss]
    [-n, --name <name>]
    [--diagnostic-port]
    [-o|--output <trace-file-path>]
    [-p|--process-id <pid>]
    [--profile <list-of-comma-separated-profile-names>]
    [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io]
    [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

Opties

  • --buffersize <size>

    Hiermee stelt u de grootte van de buffer in het geheugen in megabytes in. Standaard 256 MB.

    Notitie

    Als het doelproces gebeurtenissen sneller verzendt dan ze naar de schijf kunnen worden geschreven, kan deze buffer overlopen en worden sommige gebeurtenissen verwijderd. U kunt dit probleem oplossen door de buffergrootte te vergroten of het aantal opgenomen gebeurtenissen te verminderen.

  • --clreventlevel <clreventlevel>

    Uitgebreidheid van CLR-gebeurtenissen die moeten worden verzonden. Deze optie is alleen van toepassing wanneer --clrevents wordt opgegeven en niet wordt overschreven door --profile of --providers. In de volgende tabel ziet u de beschikbare gebeurtenisniveaus.

    Tekenreekswaarde Numerieke waarde
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Een lijst met CLR-runtimeprovidertrefwoorden om gescheiden door + tekens in te schakelen. Dit is een eenvoudige toewijzing waarmee u gebeurtenistrefwoorden kunt opgeven via tekenreeksaliassen in plaats van hun hexe waarden. Vraagt bijvoorbeeld dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 dezelfde set gebeurtenissen aan als dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Als de CLR-runtimeprovider Microsoft-Windows-DotNETRuntime ook is ingeschakeld via --providers of --profile, wordt deze optie genegeerd. In de volgende tabel ziet u de lijst met beschikbare trefwoorden:

    Alias trefwoordtekenreeks Hexwaarde voor trefwoord
    gc 0x1
    gchandle 0x2
    assemblyloader 0x4
    loader 0x8
    jit 0x10
    ngen 0x20
    startenumeration 0x40
    endenumeration 0x80
    security 0x400
    appdomainresourcemanagement 0x800
    jittracing 0x1000
    interop 0x2000
    contention 0x4000
    exception 0x8000
    threading 0x10000
    jittedmethodiltonativemap 0x20000
    overrideandsuppressngenevents 0x40000
    type 0x80000
    gcheapdump 0x100000
    gcsampledobjectallocationhigh 0x200000
    gcheapsurvivalandmovement 0x400000
    managedheapcollect 0x800000
    gcheapandtypenames 0x1000000
    gcsampledobjectallocationlow 0x2000000
    perftrack 0x20000000
    stack 0x40000000
    threadtransfer 0x80000000
    debugger 0x100000000
    monitoring 0x200000000
    codesymbols 0x400000000
    eventsource 0x800000000
    compilation 0x1000000000
    compilationdiagnostic 0x2000000000
    methoddiagnostic 0x4000000000
    typediagnostic 0x8000000000
    jitinstrumentationdata 0x10000000000
    profiler 0x20000000000
    waithandle 0x40000000000
    allocationsampling 0x80000000000

    Meer informatie over de CLR-provider vindt u in de naslagdocumentatie van de .NET-runtimeprovider.

  • '--dsrouter {ios|ios-sim|android|android-emu}

    Start dotnet-dsrouter en maakt er verbinding mee. Vereist dat dotnet-dsrouter is geïnstalleerd. Uitvoeren dotnet-dsrouter -h voor meer informatie.

  • --format {Chromium|NetTrace|Speedscope}

    Hiermee stelt u de uitvoerindeling voor de conversie van het traceringsbestand in. De standaardwaarde is NetTrace.

  • -n, --name <name>

    De naam van het proces waaruit de tracering moet worden verzameld.

    Notitie

    Voor Linux en macOS is voor het gebruik van deze optie de doeltoepassing vereist en dotnet-trace moet dezelfde omgevingsvariabele TMPDIR worden gedeeld. Anders treedt er een time-out op voor de opdracht.

  • --diagnostic-port <port-address[,(listen|connect)]>

    Hiermee stelt u de diagnostische poort in die wordt gebruikt om te communiceren met het proces dat moet worden getraceerd. dotnet-trace en de .NET-runtime binnen het doelproces moeten akkoord gaan met het poortadres, met één luisteren en de andere verbinding. dotnet-trace bepaalt automatisch de juiste poort bij het koppelen met behulp van de --process-id of --name opties, of bij het starten van een proces met behulp van de -- <command> optie. Het is meestal alleen nodig om de poort expliciet op te geven wanneer wordt gewacht op een proces dat in de toekomst begint of communiceert met een proces dat wordt uitgevoerd in een container die geen deel uitmaakt van de naamruimte van het huidige proces.

    Dit port-address verschilt per besturingssysteem:

    • Linux en macOS: een pad naar een Unix-domeinsocket zoals /foo/tool1.socket.
    • Windows : een pad naar een benoemde pijp, zoals \\.\pipe\my_diag_port1.
    • Android, iOS en tvOS - een IP:port zoals 127.0.0.1:9000.

    Luistert standaard dotnet-trace naar het opgegeven adres. U kunt in plaats daarvan aanvragen dotnet-trace om verbinding te maken door het adres toe te ,connect voegen. Maakt bijvoorbeeld --diagnostic-port /foo/tool1.socket,connect verbinding met een .NET-runtimeproces dat luistert naar de /foo/tool1.socket Unix-domeinsocket.

    Zie Diagnostische poort gebruiken om een tracering van het opstarten van apps te verzamelen voor informatie over het gebruik van deze optie.

  • --duration <time-to-run>

    De tijd waarop de tracering moet worden uitgevoerd. Gebruik de dd:hh:mm:ss indeling. U kunt deze bijvoorbeeld 00:00:00:05 5 seconden uitvoeren.

  • -o|--output <trace-file-path>

    Het uitvoerpad voor de verzamelde traceringsgegevens. Als deze niet is opgegeven, wordt deze standaard ingesteld op <appname>_<yyyyMMdd>_<HHmmss>.nettracebijvoorbeeld 'myapp_20210315_111514.nettrace'.

  • -p|--process-id <PID>

    De proces-id waaruit de tracering moet worden verzameld.

    Notitie

    Voor Linux en macOS is voor het gebruik van deze optie de doeltoepassing vereist en dotnet-trace moet dezelfde omgevingsvariabele TMPDIR worden gedeeld. Anders treedt er een time-out op voor de opdracht.

  • --profile <list-of-comma-separated-profile-names>

    Een profiel is een vooraf gedefinieerde set providerconfiguraties voor algemene traceringsscenario's. Meerdere profielen kunnen tegelijk worden opgegeven, gescheiden door komma's. Providers die zijn geconfigureerd via --providers onderdrukking van de configuratie van het profiel. Als een profiel de CLR-runtimeprovider configureert, worden alle configuraties overschreven die zijn voorgeschreven via --clrevents.

    Wanneer --profile, --providersen --clrevents worden allemaal weggelaten, dotnet-trace collect schakelt u profielen dotnet-common en dotnet-sampled-thread-time standaard in.

    Beschikbare profielen:

    Profiel Beschrijving
    dotnet-common Lichtgewicht diagnostische gegevens van .NET-runtime die zijn ontworpen om lage overhead te behouden.
    Bevat GC, AssemblyLoader, Loader, JIT, Uitzonderingen, Threading, JittedMethodILToNativeMap en Compilatiegebeurtenissen
    Gelijk aan --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Voorbeelden van .NET-threadstacks (~100 Hz) om hotspots in de loop van de tijd te identificeren. Maakt gebruik van de runtime-sample profiler met beheerde stacks.
    gc-verbose Houdt GC-verzamelingen en voorbeelden van objecttoewijzingen bij.
    gc-collect Houdt GC-verzamelingen alleen bij zeer lage overhead bij.
    database Legt ADO.NET- en Entity Framework-databaseopdrachten vast.

    Notitie

    In eerdere versies van het hulpprogramma dotnet-trace, ondersteunde het verzamelwoord een profiel met de naam cpu-sampling. Dit profiel is verwijderd omdat de naam misleidend was. Alle threads zijn gesampampleerd, ongeacht het CPU-gebruik. U kunt nu een vergelijkbaar resultaat bereiken met behulp van --profile dotnet-sampled-thread-time,dotnet-common. Als u het vroegere cpu-sampling gedrag exact wilt vergelijken, gebruikt u --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

  • --providers <list-of-comma-separated-providers>

    Een door komma's gescheiden lijst met EventPipe providers die moeten worden ingeschakeld. Deze providers vullen alle providers aan die worden geïmpliceerd door --profile <list-of-comma-separated-profile-names>. Als er inconsistentie is voor een bepaalde provider, heeft deze configuratie voorrang op de impliciete configuratie van --profile en --clrevents.

    Deze lijst met providers heeft de volgende notatie Provider[,Provider]:

    • Provider heeft de volgende notatie: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs heeft de volgende notatie: [key1=value1][;key2=value2]

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

  • -- <command> (voor doeltoepassingen met .NET 5 of hoger)

    Na de configuratieparameters van de verzameling kan de gebruiker worden toegevoegd -- , gevolgd door een opdracht om een .NET-toepassing te starten met ten minste een runtime van 5.0. Dit kan handig zijn bij het diagnosticeren van problemen die vroeg in het proces optreden, zoals opstartprestaties of assemblylaadprogramma's en binderfouten.

    Notitie

    Met deze optie wordt het eerste .NET-proces bewaakt dat met het hulpprogramma communiceert. Dit betekent dat als uw opdracht meerdere .NET-toepassingen start, alleen de eerste app wordt verzameld. Daarom is het raadzaam deze optie te gebruiken voor zelfstandige toepassingen of het gebruik van de dotnet exec <app.dll> optie.

  • --show-child-io

    Toont de invoer- en uitvoerstromen van een gestart onderliggend proces in de huidige console.

  • --resume-runtime

    Runtime hervatten zodra de sessie is geïnitialiseerd, is de standaardwaarde waar. Schakel het hervatten van runtime uit met behulp van --resume-runtime:false.

  • --stopping-event-provider-name

    Een tekenreeks die als zodanig wordt geparseerd, waardoor de tracering wordt gestopt bij het bereiken van een gebeurtenis met de overeenkomende providernaam. Voor een specifiekere stoppende gebeurtenis moet u ook opgeven --stopping-event-event-name en/of --stopping-event-payload-filter. Als u bijvoorbeeld --stopping-event-provider-name Microsoft-Windows-DotNETRuntime de tracering wilt stoppen bij het bereiken van de eerste gebeurtenis die door de Microsoft-Windows-DotNETRuntime gebeurtenisprovider is verzonden.

  • --stopping-event-event-name

    Een tekenreeks die als zodanig wordt geparseerd, waardoor de tracering wordt gestopt bij het bereiken van een gebeurtenis met de overeenkomende gebeurtenisnaam. Moet --stopping-event-provider-name worden ingesteld. Voor een specifiekere stopbeurtenis moet u ook opgeven --stopping-event-payload-filter. Als u bijvoorbeeld --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted de tracering wilt stoppen bij het bereiken van de eerste Method/JittingStarted gebeurtenis die door de Microsoft-Windows-DotNETRuntime gebeurtenisprovider is verzonden.

  • --stopping-event-payload-filter

    Een tekenreeks, geparseerd als [payload_field_name]:[payload_field_value] paren gescheiden door komma's, die de tracering stoppen bij het raken van een gebeurtenis met alle opgegeven nettoladingparen. Vereist --stopping-event-provider-name en --stopping-event-event-name moet worden ingesteld. Als u bijvoorbeeld --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick de tracering wilt stoppen bij de eerste Method/JittingStarted gebeurtenis voor de methode OnButtonClick in de Program naamruimte die door de Microsoft-Windows-DotNETRuntime gebeurtenisprovider wordt verzonden.

Notitie

  • Het stoppen van de tracering kan lang (tot minuten) duren voor grote toepassingen. De runtime moet verzenden via de typecache voor alle beheerde code die in de trace is vastgelegd.
  • Als u een tracering wilt verzamelen met behulp dotnet-tracevan, moet deze worden uitgevoerd als dezelfde gebruiker als de gebruiker die het doelproces uitvoert of als hoofdmap. Anders kan het hulpprogramma geen verbinding maken met het doelproces.
  • Als u een niet-verwerkte uitzondering ondervindt tijdens het uitvoeren dotnet-trace collect, resulteert dit in een onvolledige tracering. Als u de hoofdoorzaak van de uitzondering vindt, gaat u naar Dumps verzamelen bij crash. Als gevolg van de niet-verwerkte uitzondering wordt de tracering afgekapt wanneer de runtime wordt afgesloten om ander ongewenst gedrag te voorkomen, zoals vastlopen of beschadiging van gegevens. Hoewel de tracering onvolledig is, kunt u deze nog steeds openen om te zien wat er is gebeurd tot de fout. Er ontbreken echter Rundown-gegevens (dit gebeurt aan het einde van een tracering), zodat stacks mogelijk onopgeloste zijn (afhankelijk van de providers die zijn ingeschakeld). Open de trace door PerfView uit te voeren met de /ContinueOnError vlag op de opdrachtregel. De logboeken bevatten ook de locatie waar de uitzondering is geactiveerd.
  • Wanneer u een stopgebeurtenis opgeeft via de --stopping-event-* opties, omdat de EventStream asynchroon wordt geparseerd, zijn er enkele gebeurtenissen die passeren tussen het moment dat een traceringsgebeurtenis die overeenkomt met de opgegeven opties voor stopgebeurtenissen wordt geparseerd en de EventPipeSession wordt gestopt.

dotnet-trace collect-linux

Notitie

Het collect-linux werkwoord is een nieuwe preview-functie en is afhankelijk van een bijgewerkte versie van de .nettrace-bestandsindeling. De nieuwste PerfView-release ondersteunt deze traceringsbestanden, maar andere manieren om het traceringsbestand te gebruiken, zoals convert en report, werken mogelijk nog niet.

Verzamelt diagnostische traceringen met behulp van perf_events, een Linux-besturingssysteemtechnologie. collect-linux schakelt de volgende extra functies in via collect.

verzamelen collect-linux
Ondersteund besturingssysteem Welke dan ook Alleen Linux, kernelversie >= 6.4
Beheerders-/hoofdmachtiging vereist Nee. Yes
Alle processen tegelijk traceren Nee. Ondersteund
Systeemeigen bibliotheek- en kernel-gebeurtenissen vastleggen Nee. Ondersteund
Event callstacks bevatten systeemeigen frames Nee. Yes

Vereiste voorwaarden

  • Linux-kernel met CONFIG_USER_EVENTS=y ondersteuning (kernel 6.4+)
  • Hoofdmachtigingen
  • .NET 10+

Notitie

De collect-linux bewerking wordt alleen uitgevoerd in linux x64- en Linux arm64-omgevingen met glibc versie 2.35 of hoger. Alle .NET 10 officieel ondersteunde Linux-distributies ondersteunen deze vereiste, behalve Alpine 3.22, CentOS Stream 9 en eventuele distributies op basis van Red Hat Enterprise Linux 9. Een snelle manier om de versie van de libc van een systeem te controleren, is met de opdracht ldd --version of door de libc-bibliotheek rechtstreeks uit te voeren.

Samenvatting

dotnet-trace collect-linux
    [-h|--help]

    # Provider/Event Specification
    [--providers <list-of-comma-separated-providers>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--perf-events <list-of-perf-events>]
    [--profile <list-of-comma-separated-profile-names>]

    # Trace Collection
    [-o|--output <trace-file-path>]
    [--duration dd:hh:mm:ss]

    # .NET Process Target (Optional)
    [-n, --name <name>]
    [-p|--process-id <pid>]

    # Probe mode
    [--probe]

Standaardgedrag van verzameling

Wanneer --providers, --profile, --clreventsen --perf-events niet worden opgegeven, collect-linux schakelt u deze profielen standaard in:

  • dotnet-common — lichtgewicht diagnostische gegevens van .NET-runtime.
  • cpu-sampling — kernel CPU-steekproeven.

Standaard worden alle processen op de machine getraceerd. Als u slechts één proces wilt traceren, gebruikt -n, --name <name> u of -p|--process-id <PID>.

Opties

Opties voor provider-/gebeurtenisspecificatie

  • --providers <list-of-comma-separated-providers>

    Een door komma's gescheiden lijst met EventPipe providers die moeten worden ingeschakeld. Deze providers vullen alle providers aan die worden geïmpliceerd door --profile <list-of-comma-separated-profile-names>. Als er inconsistentie is voor een bepaalde provider, heeft deze configuratie voorrang op de impliciete configuratie van --profile en --clrevents.

    Deze lijst met providers heeft de volgende notatie Provider[,Provider]:

    • Provider heeft de volgende notatie: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs heeft de volgende notatie: [key1=value1][;key2=value2]

    Zie Bekende gebeurtenisproviders voor meer informatie over enkele bekende providers in .NET.

  • --clreventlevel <clreventlevel>

    Uitgebreidheid van CLR-gebeurtenissen die moeten worden verzonden. Deze optie is alleen van toepassing wanneer --clrevents wordt opgegeven en niet wordt overschreven door --profile of --providers. In de volgende tabel ziet u de beschikbare gebeurtenisniveaus.

    Tekenreekswaarde Numerieke waarde
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Een lijst met CLR-runtimeprovidertrefwoorden om gescheiden door + tekens in te schakelen. Dit is een eenvoudige toewijzing waarmee u gebeurtenistrefwoorden kunt opgeven via tekenreeksaliassen in plaats van hun hexe waarden. Vraagt bijvoorbeeld dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 dezelfde set gebeurtenissen aan als dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Als de CLR-runtimeprovider Microsoft-Windows-DotNETRuntime ook is ingeschakeld via --providers of --profile, wordt deze optie genegeerd. In de volgende tabel ziet u de lijst met beschikbare trefwoorden:

    Alias trefwoordtekenreeks Hexwaarde voor trefwoord
    gc 0x1
    gchandle 0x2
    assemblyloader 0x4
    loader 0x8
    jit 0x10
    ngen 0x20
    startenumeration 0x40
    endenumeration 0x80
    security 0x400
    appdomainresourcemanagement 0x800
    jittracing 0x1000
    interop 0x2000
    contention 0x4000
    exception 0x8000
    threading 0x10000
    jittedmethodiltonativemap 0x20000
    overrideandsuppressngenevents 0x40000
    type 0x80000
    gcheapdump 0x100000
    gcsampledobjectallocationhigh 0x200000
    gcheapsurvivalandmovement 0x400000
    managedheapcollect 0x800000
    gcheapandtypenames 0x1000000
    gcsampledobjectallocationlow 0x2000000
    perftrack 0x20000000
    stack 0x40000000
    threadtransfer 0x80000000
    debugger 0x100000000
    monitoring 0x200000000
    codesymbols 0x400000000
    eventsource 0x800000000
    compilation 0x1000000000
    compilationdiagnostic 0x2000000000
    methoddiagnostic 0x4000000000
    typediagnostic 0x8000000000
    jitinstrumentationdata 0x10000000000
    profiler 0x20000000000
    waithandle 0x40000000000
    allocationsampling 0x80000000000

    Meer informatie over de CLR-provider vindt u in de naslagdocumentatie van de .NET-runtimeprovider.

  • --perf-events <list-of-perf-events>

    Een door komma's gescheiden lijst met prestatiegebeurtenissen die moeten worden opgenomen in de tracering. Beschikbare gebeurtenissen vindt u onder tracefs, die doorgaans is gekoppeld aan /sys/kernel/tracing, voor available_events alle beschikbare gebeurtenissen of via de events/ submap voor gecategoriseerde gebeurtenissen.

    Voorbeeld: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

  • --profile <list-of-comma-separated-profile-names>

    Een profiel is een vooraf gedefinieerde set providerconfiguraties voor algemene traceringsscenario's. Meerdere profielen kunnen tegelijk worden opgegeven, gescheiden door komma's. Providers die zijn geconfigureerd via --providers onderdrukking van de configuratie van het profiel. Als een profiel de CLR-runtimeprovider configureert, worden alle configuraties overschreven die zijn voorgeschreven via --clrevents.

    Wanneer --profile, --providers, --clreventsen --perf-events worden allemaal weggelaten, dotnet-trace collect-linux schakelt u profielen dotnet-common en cpu-sampling standaard in.

    Beschikbare profielen:

    Profiel Beschrijving
    dotnet-common Lichtgewicht diagnostische gegevens van .NET-runtime die zijn ontworpen om lage overhead te behouden.
    Bevat GC, AssemblyLoader, Loader, JIT, Uitzonderingen, Threading, JittedMethodILToNativeMap en Compilatiegebeurtenissen
    Gelijk aan --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    cpu-sampling Kernel CPU-steekproeven (op basis van perf), verzonden als Universal.Events/cpu, voor nauwkeurige on-CPU-toeschrijving.
    thread-time Contextswitches voor kernelthreads, verzonden als Universal.Events/cswitch, voor analyse van on-CPU en scheduler.
    gc-verbose Houdt GC-verzamelingen en voorbeelden van objecttoewijzingen bij.
    gc-collect Houdt GC-verzamelingen alleen bij zeer lage overhead bij.
    database Legt ADO.NET- en Entity Framework-databaseopdrachten vast.

Opties voor traceringsverzameling

  • -o|--output <trace-file-path>

    Het uitvoerpad voor de verzamelde traceringsgegevens. Als dit niet is opgegeven, wordt deze standaard ingesteld trace_<yyyyMMdd>_<HHmmss>.nettrace op de standaard tracering voor de hele machine en voor <appname>_<yyyyMMdd>_<HHmmss>.nettrace een processpecifieke tracering (--name of --process-id)

  • --duration <time-to-run>

    De tijd waarop de tracering moet worden uitgevoerd. Gebruik de dd:hh:mm:ss indeling. U kunt deze bijvoorbeeld 00:00:00:05 5 seconden uitvoeren.

Opties voor .NET-procesdoel

Standaardgedrag van verzameling weergeven

  • -n, --name <name>

    De naam van het proces waaruit de tracering moet worden verzameld.

  • -p|--process-id <PID>

    De proces-id waaruit de tracering moet worden verzameld.

Opties voor de testmodus

  • --probe [-n|--name] [-p|--process-id] [-o|--output <stdout|output-filename>]

    Test .NET-processen voor ondersteuning van de EventPipe UserEvents IPC-opdracht die wordt gebruikt door collect-linux, zonder een tracering te verzamelen. Resultatenlijst ondersteunde processen eerst. Gebruik '-o stdout' om CSV (pid, processName, supportsCollectLinux) af te drukken op de console of '-o output-bestandsnaam' om het CSV-bestand te schrijven. Test één proces met -n|-name of -p|--process-id.

    collect-linux Omdat het uitvoeren in de testmodus geen tracering verzamelt, zijn er geen hoofdmachtigingen vereist om uit te voeren. Het biedt geen validatie van de vereisten en .NET-processen die worden uitgevoerd op preview-versies van .NET Runtime '10.0.0' worden beschouwd als niet-ondersteund.

Notitie

Als u een tracering wilt verzamelen met behulp van dotnet-trace collect-linux, moet deze worden uitgevoerd met hoofdmachtigingen (/CAP_PERFMONCAP_SYS_ADMIN). Anders kan het hulpprogramma geen gebeurtenissen verzamelen.

dotnet-trace convert

Converteert nettrace traceringen naar alternatieve indelingen voor gebruik met alternatieve hulpprogramma's voor traceringsanalyse.

Samenvatting

dotnet-trace convert [<input-filename>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

Argumenten

  • <input-filename>

    Invoertraceringsbestand dat moet worden geconverteerd. Standaard ingesteld op trace.nettrace.

Opties

  • --format <Chromium|NetTrace|Speedscope>

    Hiermee stelt u de uitvoerindeling voor de conversie van het traceringsbestand in.

  • -o|--output <output-filename>

    Uitvoerbestand. De extensie van de doelindeling wordt toegevoegd.

Notitie

Het converteren van nettrace bestanden naar chromium of speedscope bestanden kan niet ongedaan worden. speedscope en chromium bestanden hebben niet alle informatie die nodig is om bestanden te reconstrueren nettrace . De convert opdracht behoudt echter het oorspronkelijke nettrace bestand, dus verwijder dit bestand niet als u het in de toekomst wilt openen.

dotnet-trace ps

Geeft een lijst weer van de dotnet-processen waaruit traceringen kunnen worden verzameld. dotnet-trace 6.0.320703 en hoger, geeft ook de opdrachtregelargumenten weer waarmee elk proces is gestart, indien beschikbaar.

Notitie

Als u volledige informatie wilt over geïnventariseerd 64-bits processen, moet u een 64-bits versie van het dotnet-trace hulpprogramma gebruiken.

Samenvatting

dotnet-trace ps [-h|--help]

Opmerking

Stel dat u een langlopende app start met behulp van de opdracht dotnet run --configuration Release. In een ander venster voert u de dotnet-trace ps opdracht uit. De uitvoer die u ziet, is als volgt. De opdrachtregelargumenten, indien beschikbaar, worden weergegeven in dotnet-trace versie 6.0.320703 en hoger.

> dotnet-trace ps

  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

dotnet-trace list-profiles

Toont vooraf gebouwde traceringsprofielen met een beschrijving van welke providers en filters zich in elk profiel bevinden.

Samenvatting

dotnet-trace list-profiles [-h|--help]

dotnet-trace-rapport

Hiermee maakt u een rapport in stdout op basis van een eerder gegenereerde trace.

Samenvatting

dotnet-trace report [-h|--help] <tracefile> [command]

Argumenten

  • <tracefile>

    Het bestandspad voor de trace die wordt geanalyseerd.

Opdracht

dotnet-trace rapport topN

Hiermee vindt u de belangrijkste N-methoden die op de callstack het langst zijn.

Samenvatting
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
Opties
  • -n|--number <n>

Geeft de belangrijkste N-methoden op de callstack.

  • --inclusive

Voer de belangrijkste N-methoden uit op basis van inclusieve tijd. Als dit niet is opgegeven, wordt de exclusieve tijd standaard gebruikt.

  • -v|--verbose

Voer de parameters van elke methode volledig uit. Als dit niet is opgegeven, worden parameters afgekapt.

Een tracering verzamelen met dotnet-trace

Traceringen verzamelen met behulp van dotnet-trace collect:

  • Haal de proces-id (PID) van de .NET Core-toepassing op om traceringen van te verzamelen.

    • In Windows kunt u bijvoorbeeld Taakbeheer of de tasklist opdracht gebruiken.
    • In Linux bijvoorbeeld de ps opdracht.
    • dotnet-trace ps

  • Voer de volgende opdracht uit:

    dotnet-trace collect --process-id <PID>

    Met de voorgaande opdracht wordt uitvoer gegenereerd die vergelijkbaar is met de volgende:

    No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : <full-path-to-process-being-trace>
Output File    : <process>_20251007_154557.nettrace
[00:00:00:02]   Recording trace 178.172  (KB)
Press <Enter> or <Ctrl+C> to exit...
Stopping the trace. This may take several minutes depending on the application being traced.

Trace completed.

  • Stop de verzameling door op de Enter-toets te drukken. dotnet-trace de logboekregistratie van gebeurtenissen naar het .nettrace bestand wordt voltooid.

Een onderliggende toepassing starten en een tracering verzamelen bij het opstarten met behulp van dotnet-trace

Soms kan het handig zijn om een tracering van een proces te verzamelen van het opstarten. Voor apps met .NET 5 of hoger is het mogelijk om dit te doen met behulp van dotnet-trace.

Hiermee start hello.exe u met arg1 en arg2 als opdrachtregelargumenten en verzamelt u een tracering vanaf het opstarten van de runtime:

dotnet-trace collect -- hello.exe arg1 arg2

Met de voorgaande opdracht wordt uitvoer gegenereerd die vergelijkbaar is met de volgende:

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
Output File    : E:\temp\gcperfsim\trace.nettrace


[00:00:00:05]   Recording trace 122.244  (KB)
Press <Enter> or <Ctrl+C> to exit...

U kunt het verzamelen van de trace stoppen door op of <Enter> in de toets te drukken<Ctrl + C>. Als u dit doet, wordt ook afgesloten hello.exe.

Notitie

Als u hello.exe via dotnet-trace start, wordt de invoer/uitvoer omgeleid en kunt u er niet standaard mee werken op de console. Gebruik de --show-child-io schakeloptie om te communiceren met de stdin/stdout. Als u het hulpprogramma afsluit via Ctrl+C of SIGTERM, worden zowel het hulpprogramma als het onderliggende proces veilig beëindigd. Als het onderliggende proces wordt afgesloten voordat het hulpprogramma wordt afgesloten, wordt het hulpprogramma ook afgesloten en moet de trace veilig zichtbaar zijn.

Diagnostische poort gebruiken om een tracering te verzamelen van het opstarten van de app

Diagnostische poort is een runtimefunctie die is toegevoegd in .NET 5 waarmee u tracering kunt starten vanaf het opstarten van de app. Als u dit wilt doen, dotnet-tracekunt u deze gebruiken dotnet-trace collect -- <command> zoals beschreven in de bovenstaande voorbeelden of de --diagnostic-port optie gebruiken.

Het gebruik dotnet-trace <collect|monitor> -- <command> om de toepassing als onderliggend proces te starten, is de eenvoudigste manier om de toepassing snel te traceren vanaf het opstarten.

Als u echter een nauwkeurigere controle wilt krijgen over de levensduur van de app die wordt getraceerd (bijvoorbeeld de app gedurende de eerste 10 minuten bewaken en doorgaan met uitvoeren) of als u met de CLI wilt communiceren met de app, kunt u met behulp van --diagnostic-port de optie de doel-app beheren die wordt bewaakt en dotnet-trace.

  1. Met de onderstaande opdracht maakt dotnet-trace u een diagnostische socket met de naam myport.sock en wacht u op een verbinding.

    dotnet-trace collect --diagnostic-port myport.sock

    Uitvoer:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=/home/user/myport.sock

  2. Start in een afzonderlijke console de doeltoepassing met de omgevingsvariabele DOTNET_DiagnosticPorts die is ingesteld op de waarde in de dotnet-trace uitvoer.

    export DOTNET_DiagnosticPorts=/home/user/myport.sock
./my-dotnet-app arg1 arg2

    Dit moet vervolgens inschakelen dotnet-trace om tracering my-dotnet-appte starten:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=myport.sock
Starting a counter session. Press Q to quit.

    Belangrijk

    Het starten van uw app met dotnet run kan problematisch zijn, omdat de dotnet CLI veel onderliggende processen kan veroorzaken die niet uw app zijn en waarmee ze verbinding kunnen maken dotnet-trace voordat uw app, waardoor uw app tijdens runtime wordt onderbroken. Het wordt aanbevolen om rechtstreeks een zelfstandige versie van de app te gebruiken dotnet exec of om de toepassing te starten.

(Alleen Linux) Een machinebrede trace verzamelen met dotnet-trace

In dit voorbeeld worden CPU-voorbeelden vastgelegd voor alle processen op de computer. Alle processen met .NET 10+ bevatten ook enkele extra lichtgewicht gebeurtenissen die het laadgedrag van GC, JIT en Assembly beschrijven.

$ sudo dotnet-trace collect-linux
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile

Linux Perf Events                                                               Enabled By
cpu-sampling                                                                    --profile

Output File    : <path-to-nettrace>trace_20251008_181939.nettrace

[00:00:00:03]   Recording trace.
Press <Enter> or <Ctrl-C> to exit...

Recording stopped.
Resolving symbols.
Finished recording trace.
Trace written to <path-to-nettrace>trace_20251008_181939.nettrace

Voor omgevingen waarop meerdere .NET-versies zijn geïnstalleerd, collect-linux kunt u in de testmodus bepalen of een .NET-proces kan worden getraceerd met collect-linux.

$ dotnet-trace collect-linux --probe
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

De tracering weergeven die is vastgelegd vanuit dotnet-trace

In Windows kunt u .nettrace-bestanden weergeven in Visual Studio of PerfView voor analyse.

In Linux kunt u de tracering bekijken door de uitvoerindeling van dotnet-trace te wijzigen in speedscope. Wijzig de indeling van het uitvoerbestand met behulp van de -f|--format optie. U kunt kiezen tussen nettrace (de standaardoptie) en speedscope. Met de optie -f speedscope wordt dotnet-trace een speedscope bestand geproduceerd. Speedscope bestanden kunnen worden geopend op https://www.speedscope.app.

Voor traceringen die zijn verzameld op niet-Windows-platforms, kunt u het traceringsbestand ook verplaatsen naar een Windows-computer en het weergeven in Visual Studio of PerfView.

Notitie

De .NET Core-runtime genereert traceringen in de nettrace indeling. De traceringen worden geconverteerd naar speedscope (indien opgegeven) nadat de tracering is voltooid. Omdat sommige conversies kunnen leiden tot verlies van gegevens, blijft het oorspronkelijke nettrace bestand behouden naast het geconverteerde bestand.

.rsp-bestand gebruiken om te voorkomen dat lange opdrachten worden getypt

U kunt starten dotnet-trace met een .rsp bestand dat de argumenten bevat die moeten worden doorgegeven. Dit kan handig zijn bij het inschakelen van providers die lange argumenten verwachten of wanneer u een shell-omgeving gebruikt waarmee tekens worden gestript.

De volgende provider kan bijvoorbeeld lastig zijn om elke keer dat u wilt traceren uit te voeren:

dotnet-trace collect --providers Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Daarnaast bevat " het vorige voorbeeld als onderdeel van het argument. Omdat aanhalingstekens niet evenzeer door elke shell worden verwerkt, kunnen er verschillende problemen optreden bij het gebruik van verschillende shells. De opdracht die u wilt invoeren zsh , is bijvoorbeeld anders dan de opdracht in cmd.

In plaats van dit elke keer te typen, kunt u de volgende tekst opslaan in een bestand met de naam myprofile.rsp.

--providers
Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Zodra u het bestand hebt opgeslagen myprofile.rsp, kunt u met deze configuratie starten dotnet-trace met behulp van de volgende opdracht:

dotnet-trace @myprofile.rsp

Zie ook

  • Last updated on