dotnet-trace-prestandaanalysverktyg

Den här artikeln gäller för: ✔️ dotnet-trace 3.0.47001 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-trace NuGet-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:

  OS	Plattform
  Windows	x86 | x64 | Arm | Arm-x64
  Linux	x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Kommentar

Om du vill använda dotnet-trace en x86-app behöver du en motsvarande x86-version av verktyget.

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.
• Ger samma upplevelse i Windows, Linux eller macOS.

Alternativ

• -h|--help

  Visar kommandoradshjälp.

• --version

  Visar versionen av dotnet-trace-verktyget.

• --duration

  Hur lång tid det tar att köra spårningen. --duration 00:00:00:05 kör den i 5 sekunder.

Kommandon

Command
dotnet-trace collect
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>]
    [--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 <profile-name>] [--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. 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. Tabellen nedan visar listan över tillgängliga nyckelord:

  Alias för nyckelordssträng	Hexvärde för nyckelord
  gc	0x1
  gchandle	0x2
  fusion	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
  gcheapcollect	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

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

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

• --diagnostic-port <path-to-port>

  Namnet på diagnostikporten som ska skapas. Se Använda diagnostikport för att samla in en spårning från appstart för att lära dig hur du använder det här alternativet 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 <appname>_<yyyyMMdd>_<HHmmss>.nettrace, t.ex. "myapp_20210315_111514.nettrace".

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

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

• --profile <profile-name>

  En namngiven fördefinierad uppsättning providerkonfigurationer som gör att vanliga spårningsscenarier kan anges kortfattat. Följande profiler är tillgängliga:

Profil	beskrivning
cpu-sampling	Användbart för att spåra CPU-användning och allmän .NET-körningsinformation. Det här är standardalternativet om ingen profil eller providers har angetts.
gc-verbose	Spårar GC-samlingar och objektallokeringar för exempel.
gc-collect	Spårar endast GC-samlingar med mycket låg belastning.

• --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 <profile-name>. 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 profilen.

  Den här listan över leverantörer är i formatet:

  • 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 5-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. t.ex. --stopping-event-provider-name Microsoft-Windows-DotNETRuntime för att stoppa spårningen när den 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 . t.ex. --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted för att stoppa spårningen när den 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. t.ex. --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.

• I Linux och macOS förväntar sig det här kommandot målprogrammet och dotnet-trace delar samma TMPDIR miljövariabel. Annars överskrider kommandot tidsgränsen.

• 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 ser ett felmeddelande som liknar: [ERROR] System.ComponentModel.Win32Exception (299): A 32 bit processes cannot access modules of a 64 bit process.försöker du använda en version av dotnet-trace som har matchningsfel mot målprocessen. Se till att ladda ned rätt bitness för verktyget i installationslänken.

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

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:

• 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:

  Press <Enter> to exit...
  Connecting to process: <Full-Path-To-Process-Being-Profiled>/dotnet.exe
  Collecting to file: <Full-Path-To-Trace>/trace.nettrace
  Session Id: <SessionId>
  Recording trace 721.025 (KB)
  

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

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

Viktigt!

Detta fungerar endast för appar som kör .NET 5 eller senare.

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 profile 'cpu-sampling'

Provider Name                           Keywords            Level               Enabled By
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile
Microsoft-Windows-DotNETRuntime         0x00000014C14FCCBD  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

Viktigt!

Detta fungerar endast för appar som kör .NET 5 eller senare.

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.

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ända dotnet-trace för att samla in räknarvärden över tid

dotnet-trace kan:

• Används EventCounter för grundläggande hälsoövervakning i prestandakänsliga miljöer. Till exempel i produktion.
• Samla in spårningar så att de inte behöver visas i realtid.

Om du till exempel vill samla in värden för körningsprestandaräknare använder du följande kommando:

dotnet-trace collect --process-id <PID> --providers System.Runtime:0:1:EventCounterIntervalSec=1

Föregående kommando instruerar körningsräknarna att rapportera en gång i sekunden för enkel hälsoövervakning. Om du EventCounterIntervalSec=1 ersätter med ett högre värde (till exempel 60) kan du samla in en mindre spårning med mindre kornighet i räknardata.

Följande kommando minskar belastningen och spårningsstorleken mer än föregående:

dotnet-trace collect --process-id <PID> --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1

Föregående kommando inaktiverar körningshändelser och profileraren för den hanterade stacken.

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