dotnet-trace-prestandaanalysverktyg

Den här artikeln gäller för: ✔️ dotnet-trace 9.0.661903 och senare versioner

Installera

Det finns två sätt att ladda ned och installera dotnet-trace:

• dotnet global tool:

  Om du vill installera den senaste versionen av dotnet-traceNuGet-paketet använder du installationskommandot för dotnet-verktyget:

  dotnet tool install --global dotnet-trace
  

• Direkt nedladdning:

  Ladda ned det körbara verktyget som matchar din plattform:

  Olympiska Spelen (OS)	Plattform
  Windows	x86 | x64 | Arm | Arm-x64
  Linux	x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Sammanfattning

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

beskrivning

Verktyget dotnet-trace :

• Är ett plattformsoberoende .NET Core-verktyg.

• Aktiverar insamling av .NET Core-spårningar av en process som körs utan en intern profilerare.

• Bygger på EventPipe .NET Core-körningen.

• Stöder två olika sätt att samla in spårningar:

  • Verbetcollect erbjuder konsekventa funktioner i alla operativsystem.
  • Verbetcollect-linux använder Linux-specifika OS-funktioner för att tillhandahålla ytterligare funktioner.

  Egenskap	collect	collect-linux
  Operativsystem som stöds	Vilken som helst	Endast Linux, kernelversion >= 6.4
  Kräver administratörs-/rotprivilegier	Nej	Yes
  Spåra alla processer samtidigt	Nej	Understödd
  Samla in interna biblioteks- och kernelhändelser	Nej	Understödd
  Händelseanropstackar innehåller inbyggda ramar	Nej	Yes

Alternativ

• -h|--help

  Visar kommandoradshjälp.

• --version

  Visar versionen av dotnet-trace-verktyget.

Kommandon

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

dotnet-trace collect

Samlar in en diagnostikspårning från en pågående process eller startar en underordnad process och spårar den (.NET 5 eller senare). Om du vill att verktyget ska köra en underordnad -- process och spåra den från starten lägger du till i kommandot collect.

Sammanfattning

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>]

Alternativ

• --buffersize <size>

  Anger storleken på minnesintern buffert i megabyte. Standard 256 MB.

  Kommentar

  Om målprocessen genererar händelser snabbare än de kan skrivas till disken kan bufferten flöda över och vissa händelser tas bort. Du kan åtgärda det här problemet genom att öka buffertstorleken eller minska antalet händelser som registreras.

• --clreventlevel <clreventlevel>

  Utförliga CLR-händelser som ska genereras. Det här alternativet gäller endast när --clrevents anges och inte åsidosättas av --profile eller --providers. I följande tabell visas de tillgängliga händelsenivåerna.

  Strängvärde	Numeriskt värde
  logalways	0
  critical	1
  error	2
  warning	3
  informational	4
  verbose	5

• --clrevents <clrevents>

  En lista över nyckelord för CLR-körningsprovidern för att aktivera avgränsade med + tecken. Det här är en enkel mappning där du kan ange händelsenyckelord via strängalias i stället för hexvärden. Till exempel dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 begär samma uppsättning händelser som dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Om CLR-körningsprovidern Microsoft-Windows-DotNETRuntime också är aktiverad via --providers eller --profileignoreras det här alternativet. I följande tabell visas listan över tillgängliga nyckelord:

  Alias för nyckelordssträng	Hexvärde för nyckelord
  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

  Du kan läsa mer om CLR-providern i referensdokumentationen för .NET Runtime-providern.

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

  Startar dotnet-dsrouter och ansluter till den. Kräver att dotnet-dsrouter installeras. Kör dotnet-dsrouter -h för mer information.

• --format {Chromium|NetTrace|Speedscope}

  Anger utdataformatet för konverteringen av spårningsfilen. Standardvärdet är NetTrace.

• -n, --name <name>

  Namnet på den process som spårningen ska hämtas från.

  Kommentar

  I Linux och macOS kräver det här alternativet målprogrammet och dotnet-trace att samma TMPDIR miljövariabel delas. Annars överskrider kommandot tidsgränsen.

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

  Anger den diagnostikport som används för att kommunicera med den process som ska spåras. dotnet-trace och .NET-körningen i målprocessen måste komma överens om portadressen, där den ena lyssnar och den andra ansluter. dotnet-trace avgör automatiskt rätt port när du kopplar med alternativen --process-id eller --name eller när du startar en process med hjälp av -- <command> alternativet . Det är vanligtvis bara nödvändigt att uttryckligen ange porten när du väntar på en process som startar i framtiden eller kommunicerar med en process som körs i en container som inte ingår i det aktuella processnamnområdet.

  Skiljer port-address sig åt beroende på operativsystem:

  • Linux och macOS – en sökväg till en Unix-domänsocket, till exempel /foo/tool1.socket.
  • Windows – en sökväg till ett namngivet rör, till exempel \\.\pipe\my_diag_port1.
  • Android, iOS och tvOS – en IP:port som 127.0.0.1:9000.

  Som standard dotnet-trace lyssnar på den angivna adressen. Du kan begära dotnet-trace att ansluta i stället genom att lägga till ,connect efter adressen. Anslut till exempel --diagnostic-port /foo/tool1.socket,connect till en .NET-körningsprocess som lyssnar på /foo/tool1.socket Unix-domänsocketen.

  Information om hur du använder det här alternativet för att samla in en spårning från appstart finns i Använda diagnostikport för att samla in en spårning från appstart.

• --duration <time-to-run>

  Tiden för spårningen att köras. dd:hh:mm:ss Använd formatet. Till exempel 00:00:00:05 körs den i 5 sekunder.

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

  Utdatasökvägen för insamlade spårningsdata. Om det inte anges är standardvärdet , till <appname>_<yyyyMMdd>_<HHmmss>.nettraceexempel "myapp_20210315_111514.nettrace".

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

  Process-ID:t som spårningen ska hämtas från.

  Kommentar

  I Linux och macOS kräver det här alternativet målprogrammet och dotnet-trace att samma TMPDIR miljövariabel delas. Annars överskrider kommandot tidsgränsen.

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

  En profil är en fördefinierad uppsättning providerkonfigurationer för vanliga spårningsscenarier. Flera profiler kan anges i taget, avgränsade med kommatecken. Leverantörer som konfigurerats via --providers åsidosätter profilens konfiguration. På samma sätt, om någon profil konfigurerar CLR-körningsprovidern, åsidosätter den alla konfigurationer som föreskrivs via --clrevents.

  När --profile, --providersoch --clrevents utelämnas, dotnet-trace collect aktiverar profiler dotnet-common och dotnet-sampled-thread-time som standard.

  Tillgängliga profiler:

  Profil	beskrivning
  dotnet-common	Enkel .NET-körningsdiagnostik som är utformad för att hålla nere kostnaderna. Innehåller händelser för GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap och Compilation Motsvarar --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
  dotnet-sampled-thread-time	Exempel på .NET-trådstackar (~100 Hz) för att identifiera hotspots över tid. Använder körningsexempelprofileraren med hanterade staplar.
  gc-verbose	Spårar GC-samlingar och objektallokeringar för exempel.
  gc-collect	Spårar endast GC-samlingar med mycket låg belastning.
  database	Samlar in databaskommandon för ADO.NET och Entity Framework.

  Kommentar

  I tidigare versioner av dotnet-trace-verktyget stödde insamlingsverb en profil med namnet cpu-sampling. Profilen togs bort eftersom namnet var missvisande. Alla trådar har samplats oavsett cpu-användning. Du kan uppnå ett liknande resultat nu med hjälp av --profile dotnet-sampled-thread-time,dotnet-common. Om du behöver matcha det tidigare cpu-sampling beteendet exakt använder du --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

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

  En kommaavgränsad lista över EventPipe leverantörer som ska aktiveras. Dessa leverantörer kompletterar alla leverantörer som underförstås av --profile <list-of-comma-separated-profile-names>. Om det finns någon inkonsekvens för en viss provider har den här konfigurationen företräde framför den implicita konfigurationen från --profile och --clrevents.

  Den här listan över leverantörer är i formuläret Provider[,Provider]:

  • Provider är i formuläret: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
  • KeyValueArgs är i formuläret: [key1=value1][;key2=value2]

  Mer information om några av de välkända leverantörerna i .NET finns i Välkända händelseleverantörer.

• -- <command> (för målprogram som kör .NET 5 eller senare)

  Efter insamlingskonfigurationsparametrarna kan användaren lägga till -- följt av ett kommando för att starta ett .NET-program med minst en 5.0-körning. Detta kan vara användbart när du diagnostiserar problem som inträffar tidigt i processen, till exempel problem med startprestanda eller monteringsinläsare och bindemedelsfel.

  Kommentar

  Med det här alternativet övervakas den första .NET-processen som kommunicerar tillbaka till verktyget, vilket innebär att om kommandot startar flera .NET-program samlar det bara in den första appen. Därför rekommenderar vi att du använder det här alternativet i fristående program eller med hjälp av alternativet dotnet exec <app.dll> .

• --show-child-io

  Visar in- och utdataströmmarna för en underordnad process som startas i den aktuella konsolen.

• --resume-runtime

  Återuppta körningen när sessionen har initierats, standardvärdet är true. Inaktivera återupptad körning med hjälp av --resume-runtime:false.

• --stopping-event-provider-name

  En sträng, tolkad som den är, som stoppar spårningen när den träffar en händelse med det matchande providernamnet. För en mer specifik stopphändelse anger --stopping-event-event-name du dessutom och/eller --stopping-event-payload-filter. till exempel --stopping-event-provider-name Microsoft-Windows-DotNETRuntime för att stoppa spårningen när du träffar den första händelsen som genereras av Microsoft-Windows-DotNETRuntime händelseprovidern.

• --stopping-event-event-name

  En sträng, tolkad som den är, som stoppar spårningen när den träffar en händelse med det matchande händelsenamnet. Kräver --stopping-event-provider-name att anges. För en mer specifik stopphändelse anger du --stopping-event-payload-filterdessutom . till exempel --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted för att stoppa spårningen när du träffar den första Method/JittingStarted händelsen som genereras av Microsoft-Windows-DotNETRuntime händelseprovidern.

• --stopping-event-payload-filter

  En sträng, parsad som [payload_field_name]:[payload_field_value] par avgränsade med kommatecken, som stoppar spårningen när du träffar en händelse som innehåller alla angivna nyttolastpar. Kräver --stopping-event-provider-name och --stopping-event-event-name måste anges. Till exempel --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick för att stoppa spårningen vid den första Method/JittingStarted händelsen för metoden OnButtonClick i det Program namnområde som genereras av Microsoft-Windows-DotNETRuntime händelseprovidern.

Kommentar

• Det kan ta lång tid (upp till minuter) att stoppa spårningen för stora program. Körningen måste skicka över typcachen för all hanterad kod som har registrerats i spårningen.

• För att samla in en spårning med måste dotnet-traceden köras som samma användare som användaren som kör målprocessen eller som rot. Annars kan verktyget inte upprätta en anslutning till målprocessen.

• Om du får ett ohanterat undantag när du kör dotnet-trace collectresulterar detta i en ofullständig spårning. Om du har prioritet att hitta rotorsaken till undantaget går du till Samla in dumpar vid krasch. Som ett resultat av det ohanterade undantaget trunkeras spårningen när körningen stängs av för att förhindra andra oönskade beteenden, till exempel låsning eller skadade data. Även om spårningen är ofullständig kan du fortfarande öppna den för att se vad som hände som ledde till felet. Den kommer dock att sakna Rundown-information (detta händer i slutet av en spårning) så staplar kan vara olösta (beroende på vilka leverantörer som har aktiverats). Öppna spårningen genom att köra PerfView med /ContinueOnError flaggan på kommandoraden. Loggarna innehåller också platsen där undantaget utlöstes.

• När du anger en stopphändelse via --stopping-event-* alternativen, eftersom EventStream parsas asynkront, kommer det att finnas vissa händelser som passerar mellan den tidpunkt då en spårningshändelse som matchar de angivna alternativen för stopphändelser parsas och EventPipeSession stoppas.

dotnet-trace collect-linux

Kommentar

Verbet collect-linux är en ny förhandsgranskningsfunktion och förlitar sig på en uppdaterad version av .nettrace-filformatet. Den senaste Versionen av PerfView stöder dessa spårningsfiler, men andra sätt att använda spårningsfilen, till exempel convert och report, kanske inte fungerar ännu.

Samlar in diagnostikspårningar med hjälp av perf_events, en Linux OS-teknik. collect-linux aktiverar följande ytterligare funktioner över collect.

Egenskap	collect	collect-linux
Operativsystem som stöds	Vilken som helst	Endast Linux, kernelversion >= 6.4
Kräver administratörs-/rotprivilegier	Nej	Yes
Spåra alla processer samtidigt	Nej	Understödd
Samla in interna biblioteks- och kernelhändelser	Nej	Understödd
Händelseanropstackar innehåller inbyggda ramar	Nej	Yes

Förutsättningar

• Linux-kernel med CONFIG_USER_EVENTS=y stöd (kernel 6.4+)
• Rotbehörigheter
• .NET 10+

Kommentar

Verbet collect-linux körs endast på linux x64- och linux arm64-miljöer som har glibc version 2.35 eller senare. Alla .NET 10-distributioner som stöds officiellt stöder detta krav förutom Alpine 3.22, CentOS Stream 9 och eventuella distributioner baserade på Red Hat Enterprise Linux 9. Ett snabbt sätt att kontrollera versionen av ett systems libc är med kommandot ldd --version eller genom att köra libc-biblioteket direkt.

Sammanfattning

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]

Standardbeteende för samling

När --providers, --profile, --clreventsoch --perf-events inte har angetts aktiverar collect-linux du dessa profiler som standard:

• dotnet-common – enkel .NET-körningsdiagnostik.
• cpu-sampling — Kernel CPU-sampling.

Som standard spåras alla processer på datorn. Om du bara vill spåra en process använder du -n, --name <name> eller -p|--process-id <PID>.

Alternativ

Alternativ för provider/händelsespecifikation

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

  En kommaavgränsad lista över EventPipe leverantörer som ska aktiveras. Dessa leverantörer kompletterar alla leverantörer som underförstås av --profile <list-of-comma-separated-profile-names>. Om det finns någon inkonsekvens för en viss provider har den här konfigurationen företräde framför den implicita konfigurationen från --profile och --clrevents.

  Den här listan över leverantörer är i formuläret Provider[,Provider]:

  • Provider är i formuläret: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
  • KeyValueArgs är i formuläret: [key1=value1][;key2=value2]

  Mer information om några av de välkända leverantörerna i .NET finns i Välkända händelseprovidrar.

• --clreventlevel <clreventlevel>

  Utförliga CLR-händelser som ska genereras. Det här alternativet gäller endast när --clrevents anges och inte åsidosättas av --profile eller --providers. I följande tabell visas de tillgängliga händelsenivåerna.

  Strängvärde	Numeriskt värde
  logalways	0
  critical	1
  error	2
  warning	3
  informational	4
  verbose	5

• --clrevents <clrevents>

  En lista över nyckelord för CLR-körningsprovidern för att aktivera avgränsade med + tecken. Det här är en enkel mappning där du kan ange händelsenyckelord via strängalias i stället för hexvärden. Till exempel dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 begär samma uppsättning händelser som dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Om CLR-körningsprovidern Microsoft-Windows-DotNETRuntime också är aktiverad via --providers eller --profileignoreras det här alternativet. I följande tabell visas listan över tillgängliga nyckelord:

  Alias för nyckelordssträng	Hexvärde för nyckelord
  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

  Du kan läsa mer om CLR-providern i referensdokumentationen för .NET Runtime-providern.

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

  En kommaavgränsad lista över perf-händelser som ska inkluderas i spårningen. Tillgängliga händelser finns under tracefs, som vanligtvis monteras på /sys/kernel/tracing, genom available_events för alla tillgängliga händelser eller via underkatalogen events/ för kategoriserade händelser.

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

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

  En profil är en fördefinierad uppsättning providerkonfigurationer för vanliga spårningsscenarier. Flera profiler kan anges i taget, avgränsade med kommatecken. Leverantörer som konfigurerats via --providers åsidosätter profilens konfiguration. På samma sätt, om någon profil konfigurerar CLR-körningsprovidern, åsidosätter den alla konfigurationer som föreskrivs via --clrevents.

  När --profile, --providers, --clreventsoch --perf-events utelämnas, dotnet-trace collect-linux aktiverar profiler dotnet-common och cpu-sampling som standard.

  Tillgängliga profiler:

  Profil	beskrivning
  dotnet-common	Enkel .NET-körningsdiagnostik som är utformad för att hålla nere kostnaderna. Innehåller händelser för GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap och Compilation Motsvarar --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
  cpu-sampling	Kernel CPU-sampling (perf-baserad), som genereras som Universal.Events/cpu, för exakt attribution på CPU.
  thread-time	Kernel-trådkontextväxlar, som genereras som Universal.Events/cswitch, för analys av on/off-CPU och scheduler.
  gc-verbose	Spårar GC-samlingar och objektallokeringar för exempel.
  gc-collect	Spårar endast GC-samlingar med mycket låg belastning.
  database	Samlar in databaskommandon för ADO.NET och Entity Framework.

Alternativ för spårningsinsamling

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

  Utdatasökvägen för insamlade spårningsdata. Om det inte anges är trace_<yyyyMMdd>_<HHmmss>.nettrace standardvärdet för standardspårningen för hela datorn och för <appname>_<yyyyMMdd>_<HHmmss>.nettrace en processspecifik spårning (--name eller --process-id)

• --duration <time-to-run>

  Tiden för spårningen att köras. dd:hh:mm:ss Använd formatet. Till exempel 00:00:00:05 körs den i 5 sekunder.

Alternativ för .NET-processmål

Se Standardbeteende för samling

• -n, --name <name>

  Namnet på den process som spårningen ska hämtas från.

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

  Process-ID:t som spårningen ska hämtas från.

Alternativ för avsökningsläge

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

  Avsöka .NET-processer för stöd för EventPipe UserEvents IPC-kommandot som används av collect-linux, utan att samla in en spårning. Resultatlista som stöds processer först. Använd "-o stdout" för att skriva ut CSV (pid,processName,supportsCollectLinux) till konsolen eller "-o output-filename" för att skriva CSV:n. Avsöka en enskild process med -n|--name eller -p|--process-id.

  Eftersom körning collect-linux i avsökningsläge inte samlar in en spårning krävs inte rotbehörigheter för att köras. Den tillhandahåller inte verifiering av förhandskraven och .NET-processer som körs på förhandsversioner av .NET Runtime '10.0.0' anses inte ha stöd.

Kommentar

För att samla in en spårning med måste dotnet-trace collect-linuxden köras med rotbehörigheter (CAP_PERFMON/CAP_SYS_ADMIN). Annars misslyckas verktyget med att samla in händelser.

dotnet-trace convert

Konverterar spårningar nettrace till alternativa format för användning med alternativa verktyg för spårningsanalys.

Sammanfattning

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

Argument

• <input-filename>

  Indataspårningsfil som ska konverteras. Standardvärdet är trace.nettrace.

Alternativ

• --format <Chromium|NetTrace|Speedscope>

  Anger utdataformatet för konverteringen av spårningsfilen.

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

  Utdatafilnamn. Tillägg av målformat läggs till.

Kommentar

Det går inte att nettrace konvertera filer till chromium eller speedscope filer. speedscope och chromium filer har inte all information som behövs för att rekonstruera nettrace filer. Kommandot bevarar dock convert den ursprungliga nettrace filen, så ta inte bort den här filen om du planerar att öppna den i framtiden.

dotnet-trace ps

Visar en lista över de dotnet-processer som spårningar kan samlas in från. dotnet-trace 6.0.320703 och senare visar även de kommandoradsargument som varje process startades med, om den är tillgänglig.

Kommentar

För att få fullständig information om uppräknade 64-bitarsprocesser måste du använda en 64-bitarsversion av dotnet-trace verktyget.

Sammanfattning

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

Exempel

Anta att du startar en tidskrävande app med kommandot dotnet run --configuration Release. I ett annat fönster kör dotnet-trace ps du kommandot . Utdata visas på följande sätt. Kommandoradsargumenten, om de är tillgängliga, visas i dotnet-trace version 6.0.320703 och senare.

> 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

Visar fördefinierade spårningsprofiler med en beskrivning av vilka leverantörer och filter som finns i varje profil.

Sammanfattning

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

dotnet-trace-rapport

Skapar en rapport i stdout från en tidigare genererad spårning.

Sammanfattning

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

Argument

• <tracefile>

  Filsökvägen för spårningen som analyseras.

Kommandon

dotnet-trace report topN

Hittar de främsta N-metoderna som har varit på anropsstacken längst.

Sammanfattning

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

Alternativ

• -n|--number <n>

Ger de översta N-metoderna i anropsstacken.

• --inclusive

Mata ut de översta N-metoderna baserat på inkluderande tid. Om det inte anges används exklusiv tid som standard.

• -v|--verbose

Mata ut parametrarna för varje metod i sin helhet. Om det inte anges trunkeras parametrarna.

Samla in en spårning med dotnet-trace

Samla in spårningar med hjälp av dotnet-trace collect:

• Hämta processidentifieraren (PID) för .NET Core-programmet för att samla in spårningar från.

  • I Windows kan du till exempel använda Aktivitetshanteraren eller tasklist kommandot.
  • I Linux, till exempel ps kommandot.
  • dotnet-trace ps

• Kör följande kommando:

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

  Föregående kommando genererar utdata som liknar följande:

  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.
  

• Stoppa samlingen genom att trycka på Retur . dotnet-trace kommer att slutföra loggningshändelser till .nettrace filen.

Starta ett underordnat program och samla in en spårning från starten med dotnet-trace

Ibland kan det vara användbart att samla in en spårning av en process från starten. För appar som kör .NET 5 eller senare är det möjligt att göra detta med hjälp av dotnet-trace.

Detta startar hello.exe med arg1 och arg2 som kommandoradsargument och samlar in en spårning från körningsstarten:

dotnet-trace collect -- hello.exe arg1 arg2

Föregående kommando genererar utdata som liknar följande:

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...

Du kan sluta samla in spårningen genom att trycka <Enter> eller <Ctrl + C> trycka på den. Om du gör det avslutas hello.exeockså .

Kommentar

Om du startar hello.exe via dotnet-trace omdirigeras dess indata/utdata och du kommer inte att kunna interagera med den i konsolen som standard. Använd växeln --show-child-io för att interagera med dess stdin/stdout. Om du avslutar verktyget via CTRL+C eller SIGTERM avslutas både verktyget och den underordnade processen på ett säkert sätt. Om den underordnade processen avslutas innan verktyget avslutas även verktyget och spårningen ska vara säkert synlig.

Använda diagnostikport för att samla in en spårning från appstart

Diagnostikport är en körningsfunktion som lagts till i .NET 5 som gör att du kan börja spåra från appstart. Om du vill göra detta med kan dotnet-tracedu antingen använda dotnet-trace collect -- <command> enligt beskrivningen i exemplen ovan eller använda alternativet --diagnostic-port .

Att använda dotnet-trace <collect|monitor> -- <command> för att starta programmet som en underordnad process är det enklaste sättet att snabbt spåra programmet från starten.

Men när du vill få en finare kontroll över appens livslängd som spåras (till exempel övervaka appen under de första 10 minuterna och fortsätta köra) eller om du behöver interagera med appen med hjälp av CLI kan du med hjälp av --diagnostic-port alternativet styra både målappen som övervakas och dotnet-trace.

1. Kommandot nedan skapar dotnet-trace en diagnostik socket med namnet myport.sock och väntar på en anslutning.

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

   Utdata:

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

2. Starta målprogrammet i en separat konsol med miljövariabeln DOTNET_DiagnosticPorts inställd på värdet i dotnet-trace utdata.

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

   Detta bör sedan aktivera dotnet-trace för att börja spåra my-dotnet-app:

   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.
   

   Viktigt!

   Det kan vara problematiskt att starta din app med dotnet run eftersom dotnet CLI kan skapa många underordnade processer som inte är din app och de kan ansluta till dotnet-trace innan din app, vilket gör att appen pausas vid körning. Vi rekommenderar att du direkt använder en fristående version av appen eller använder dotnet exec för att starta programmet.

(Endast Linux) Samla in en datoromfattande spårning med dotnet-trace

I det här exemplet avbildas CPU-exempel för alla processer på datorn. Alla processer som kör .NET 10+ innehåller även några ytterligare lätta händelser som beskriver GC-, JIT- och sammansättningsinläsningsbeteende.

$ 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

För miljöer med flera .NET-versioner installerade hjälper körning collect-linux i avsökningsläge till att avgöra om en .NET-process kan spåras med 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'

Visa spårningen som hämtats från dotnet-trace

I Windows kan du visa .nettrace-filer i Visual Studio eller PerfView för analys.

I Linux kan du visa spårningen genom att ändra utdataformatet dotnet-trace till speedscope. Ändra utdatafilformatet med hjälp -f|--format av alternativet . Du kan välja mellan nettrace (standardalternativet) och speedscope. Alternativet -f speedscope gör att du skapar dotnet-trace en speedscope fil. Speedscope filer kan öppnas på https://www.speedscope.app.

För spårningar som samlas in på andra plattformar än Windows kan du också flytta spårningsfilen till en Windows-dator och visa den i Visual Studio eller PerfView.

Kommentar

.NET Core-körningen genererar spårningar i nettrace formatet. Spårningarna konverteras till speedscope (om det anges) när spårningen har slutförts. Eftersom vissa konverteringar kan leda till dataförlust bevaras den ursprungliga nettrace filen bredvid den konverterade filen.

Använd .rsp-filen för att undvika att skriva långa kommandon

Du kan starta dotnet-trace med en .rsp fil som innehåller argumenten som ska skickas. Detta kan vara användbart när du aktiverar leverantörer som förväntar sig långa argument eller när du använder en gränssnittsmiljö som tar bort tecken.

Följande provider kan till exempel vara besvärlig att skriva ut varje gång du vill spåra:

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

Dessutom innehåller " föregående exempel som en del av argumentet. Eftersom citattecken inte hanteras lika av varje gränssnitt kan det uppstå olika problem när du använder olika gränssnitt. Kommandot som ska anges i zsh skiljer sig till exempel från kommandot i cmd.

I stället för att skriva detta varje gång kan du spara följande text i en fil med namnet 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

När du har sparat myprofile.rspkan du starta dotnet-trace med den här konfigurationen med hjälp av följande kommando:

dotnet-trace @myprofile.rsp

Se även

• Välkända händelseprovidrar från .NET