Sdílet prostřednictvím

nástroj pro analýzu výkonu dotnet-trace

  • Článek

Tento článek se vztahuje na: ✔️ dotnet-trace 3.0.47001 a novější verze

Instalace

Existují dva způsoby, jak stáhnout a nainstalovat dotnet-trace:

Synopse

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

Popis

Nástroj dotnet-trace :

  • Je multiplatformní nástroj .NET Core.
  • Umožňuje kolekci trasování .NET Core spuštěného procesu bez nativního profileru.
  • Je postaven na EventPipe modulu runtime .NET Core.
  • Poskytuje stejné prostředí ve Windows, Linuxu nebo macOS.

Možnosti

  • -h|--help

    Zobrazuje nápovědu k příkazovému řádku.

  • --version

    Zobrazí verzi nástroje dotnet-trace.

  • --duration

    Jak dlouho se má trasování spustit. --duration 00:00:00:05 spustí ho po dobu 5 sekund.

Příkazy

Příkaz
dotnet-trace collect
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace report

dotnet-trace collect

Shromažďuje diagnostické trasování ze spuštěného procesu nebo spouští podřízený proces a trasuje ho (.NET 5 nebo novější). Pokud chcete, aby nástroj spustil podřízený proces a trasování z jeho spuštění, připojte -- ho k příkazu collect.

Synopse

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

Možnosti

  • --buffersize <size>

    Nastaví velikost vyrovnávací paměti v megabajtech. Výchozí 256 MB.

    Poznámka:

    Pokud cílový proces generuje události rychleji, než je možné zapisovat na disk, může tato vyrovnávací paměť přetékat a některé události se zahodí. Tento problém můžete zmírnit zvýšením velikosti vyrovnávací paměti nebo snížením počtu zaznamenaných událostí.

  • --clreventlevel <clreventlevel>

    Úroveň podrobností událostí CLR, které se mají vygenerovat. V následující tabulce jsou uvedeny dostupné úrovně událostí.

    Řetězcová hodnota Číselná hodnota
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Seznam klíčových slov zprostředkovatele modulu runtime CLR, která povolí oddělení znaménkami + . Toto je jednoduché mapování, které umožňuje zadat klíčová slova událostí prostřednictvím řetězcových aliasů místo jejich šestnáctkových hodnot. Například dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 vyžaduje stejnou sadu událostí jako dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Následující tabulka ukazuje seznam dostupných klíčových slov:

    Alias řetězce klíčového slova Hexní hodnota klíčového slova
    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

    O poskytovateli CLR si můžete přečíst podrobněji v referenční dokumentaci k zprostředkovateli modulu runtime .NET.

  • --format {Chromium|NetTrace|Speedscope}

    Nastaví výstupní formát pro převod trasovacích souborů. Výchozí hodnota je NetTrace.

  • -n, --name <name>

    Název procesu pro shromáždění trasování.

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

    Název diagnostického portu, který se má vytvořit. Informace o použití této možnosti ke shromažďování trasování od spuštění aplikace najdete v tématu Použití diagnostického portu ke shromažďování trasování od spuštění aplikace.

  • --duration <time-to-run>

    Čas spuštění trasování. dd:hh:mm:ss Použijte formát. Například 00:00:00:05 se spustí po dobu 5 sekund.

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

    Výstupní cesta pro shromážděná data trasování. Pokud není zadána výchozí hodnota <appname>_<yyyyMMdd>_<HHmmss>.nettrace, například "myapp_20210315_111514.nettrace".

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

    ID procesu, ze které se má trasování shromáždit.

  • --profile <profile-name>

    Pojmenovaná předem definovaná sada konfigurací zprostředkovatele, která umožňuje stručné zadání běžných scénářů trasování. K dispozici jsou následující profily:

Profil Popis
cpu-sampling Užitečné pro sledování využití procesoru a obecné informace o modulu runtime .NET. Toto je výchozí možnost, pokud nejsou zadány žádné profily nebo zprostředkovatelé.
gc-verbose Sleduje přidělení objektů a kolekcí uvolňování paměti.
gc-collect Sleduje kolekce uvolňování paměti pouze při velmi nízké režii.

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

    Seznam poskytovatelů oddělených EventPipe čárkami, které se mají povolit. Tito poskytovatelé doplňují všechny poskytovatele odvozené .--profile <profile-name> Pokud je pro konkrétního poskytovatele nějaká nekonzistence, má tato konfigurace přednost před implicitní konfigurací z profilu.

    Tento seznam poskytovatelů je ve formátu:

    • Provider[,Provider]
    • Provider je ve formě: KnownProviderName[:Flags[:Level][:KeyValueArgs]].
    • KeyValueArgs je ve formě: [key1=value1][;key2=value2].

    Další informace o některých známých poskytovatelích v .NET najdete v části Známé zprostředkovatele událostí.

  • -- <command> (pro cílové aplikace se systémem .NET 5 nebo novějším)

    Po parametrech konfigurace kolekce může uživatel připojit -- následovaný příkazem pro spuštění aplikace .NET s alespoň modulem runtime 5.0. To může být užitečné při diagnostice problémů, ke kterým dochází v rané fázi procesu, jako jsou problémy s výkonem při spuštění nebo zavaděč sestavení a chyby pořadače.

    Poznámka:

    Tato možnost monitoruje první proces .NET, který komunikuje zpět s nástrojem, což znamená, že pokud váš příkaz spustí více aplikací .NET, bude shromažďovat pouze první aplikaci. Proto se doporučuje tuto možnost použít u samostatných aplikací nebo použití této dotnet exec <app.dll> možnosti.

  • --show-child-io

    Zobrazuje vstupní a výstupní datové proudy spuštěného podřízeného procesu v aktuální konzole.

  • --resume-runtime

    Obnovení modulu runtime po inicializaci relace je výchozí hodnota true. Zakažte obnovení modulu runtime pomocí parametru --resume-runtime:false.

  • --stopping-event-provider-name

    Řetězec, parsovaný tak, že zastaví trasování po dosažení události s odpovídajícím názvem zprostředkovatele. Pokud chcete konkrétnější událost zastavení, uveďte --stopping-event-event-name a/nebo --stopping-event-payload-filter. Například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime zastavení trasování při dosažení první události, kterou Microsoft-Windows-DotNETRuntime vygeneruje poskytovatel události.

  • --stopping-event-event-name

    Řetězec, parsovaný tak, že zastaví trasování po dosažení události s odpovídajícím názvem události. Vyžaduje --stopping-event-provider-name nastavení. Pro konkrétnější událost zastavení navíc uveďte --stopping-event-payload-filter. Například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted zastavení trasování při dosažení první Method/JittingStarted události, kterou Microsoft-Windows-DotNETRuntime vygeneruje poskytovatel události.

  • --stopping-event-payload-filter

    Řetězec parsovaný jako [payload_field_name]:[payload_field_value] oddělené čárkami, který zastaví trasování při dosažení události obsahující všechny zadané páry datové části. Vyžaduje --stopping-event-provider-name a --stopping-event-event-name musí být nastaven. Například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick zastavení trasování při první Method/JittingStarted události pro metodu OnButtonClick v Program oboru názvů generovaném poskytovatelem Microsoft-Windows-DotNETRuntime události.

Poznámka:

  • Zastavení trasování může u velkých aplikací trvat delší dobu (až minuty). Modul runtime musí odesílat přes mezipaměť typů pro veškerý spravovaný kód zachycený v trasování.
  • V Linuxu a macOS tento příkaz očekává cílovou aplikaci a dotnet-trace bude sdílet stejnou proměnnou TMPDIR prostředí. Jinak vyprší časový limit příkazu.
  • Pokud chcete shromáždit trasování pomocí dotnet-trace, musí být spuštěn jako stejný uživatel jako uživatel, který spouští cílový proces nebo jako kořen. Jinak se nástroj nepodaří navázat spojení s cílovým procesem.
  • Pokud při spuštění dotnet-trace collectdojde k neošetřené výjimce, výsledkem je neúplné trasování. Pokud je vaší prioritou zjištění původní příčiny výjimky, přejděte do části Shromáždit výpisy stavu systému v případě chybového ukončení. V důsledku neošetřené výjimky se trasování zkrátí, když se modul runtime vypne, aby se zabránilo dalšímu nežádoucímu chování, jako je zablokování nebo poškození dat. I když je trasování neúplné, můžete ho přesto otevřít, abyste zjistili, co se stalo, což vedlo k selhání. Na konci trasování ale chybí informace o rundownu (k tomu dochází na konci trasování), takže zásobníky můžou být nevyřešeny (v závislosti na tom, jaké poskytovatele byly zapnuté). Spuštěním perfView s /ContinueOnError příznakem na příkazovém řádku otevřete trasování. Protokoly budou obsahovat také umístění, ve které byla výjimka aktivována.
  • Při zadávání události zastavení prostřednictvím --stopping-event-* možností, protože EventStream probíhá asynchronně, budou existovat některé události, které procházejí mezi časem, kdy se událost trasování odpovídající zadaným možnostem zastavení události parsuje a eventPipeSession se zastaví.

dotnet-trace convert

nettrace Převede trasování na alternativní formáty pro použití s nástroji pro analýzu alternativních trasování.

Synopse

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

Argumenty

  • <input-filename>

    Vstupní trasovací soubor, který se má převést. Výchozí hodnota je trace.nettrace.

Možnosti

  • --format <Chromium|NetTrace|Speedscope>

    Nastaví výstupní formát pro převod trasovacích souborů.

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

    Výstupní název souboru Přidá se rozšíření cílového formátu.

Poznámka:

Převod nettrace souborů na chromium soubory nebo speedscope soubory je nevratný. speedscope a chromium soubory nemají všechny informace potřebné k rekonstrukci nettrace souborů. convert Příkaz však zachová původní nettrace soubor, takže ho neodstraňovat, pokud ho budete chtít otevřít v budoucnu.

dotnet-trace ps

Obsahuje seznam procesů dotnet, ze které lze shromažďovat trasování. dotnet-trace 6.0.320703 a novější zobrazte také argumenty příkazového řádku, se kterými byly jednotlivé procesy spuštěny, pokud jsou k dispozici.

Poznámka:

Pokud chcete získat úplné informace pro výčet 64bitových procesů, musíte použít 64bitovou verzi dotnet-trace nástroje.

Synopse

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

Příklad

Předpokládejme, že spustíte dlouhotrvající aplikaci pomocí příkazu dotnet run --configuration Release. V jiném okně spustíte dotnet-trace ps příkaz. Výstup, který uvidíte, je následující. Argumenty příkazového řádku, pokud jsou k dispozici, se zobrazují ve dotnet-trace verzi 6.0.320703 a novější.

> 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

Uvádí předem vytvořené profily trasování s popisem, jaké zprostředkovatele a filtry jsou v jednotlivých profilech.

Synopse

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

dotnet-trace report

Vytvoří sestavu do stdoutu z dříve vygenerovaného trasování.

Synopse

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

Argumenty

  • <tracefile>

    Cesta k souboru analyzovaného trasování.

Příkazy

dotnet-trace report topN

Vyhledá horní N metody, které byly v náznamku volání nejdelší.

Synopse
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
Možnosti
  • -n|--number <n>

Dává horní N metody na volání.

  • --inclusive

Výstup hlavních N metod založených na inkluzivním čase Pokud nezadáte, použije se ve výchozím nastavení výhradní čas.

  • -v|--verbose

Vypište parametry každé metody v plném rozsahu. Pokud není zadáno, parametry budou zkráceny.

Shromáždění trasování pomocí dotnet-trace

Shromažďování trasování pomocí dotnet-trace:

  • Získejte identifikátor procesu (PID) aplikace .NET Core, ze které se shromažďují trasování.

    • Ve Windows můžete například použít Správce úloh nebo tasklist příkaz.
    • Například v Linuxu příkaz ps .
    • dotnet-trace ps

  • Spusťte následující příkaz:

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

    Předchozí příkaz generuje výstup podobný následujícímu:

    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)

  • Zastavte shromažďování stisknutím klávesy <Enter> . dotnet-trace dokončí protokolování událostí do souboru trace.nettrace .

Spuštění podřízené aplikace a shromáždění trasování ze spuštění pomocí dotnet-trace

Někdy může být užitečné shromáždit trasování procesu od jeho spuštění. U aplikací, na kterých běží .NET 5 nebo novější, je to možné provést pomocí dotnet-trace.

Tím se spustí hello.exe arg1 argumenty příkazového řádku a arg2 shromáždí se trasování z spuštění modulu runtime:

dotnet-trace collect -- hello.exe arg1 arg2

Předchozí příkaz generuje výstup podobný následujícímu:

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

Trasování můžete zastavit stisknutím nebo <Ctrl + C> klávesou<Enter>. Tím dojde také k ukončení hello.exe.

Poznámka:

hello.exe Spuštění přes dotnet-trace přesměruje jeho vstup/výstup a ve výchozím nastavení s ním nebudete moct pracovat v konzole. --show-child-io Pomocí přepínače můžete pracovat s jeho stdin/stdout. Ukončení nástroje pomocí kombinace kláves CTRL+C nebo SIGTERM bezpečně ukončí nástroj i podřízený proces. Pokud se podřízený proces ukončí před nástrojem, nástroj se ukončí a trasování by mělo být bezpečně zobrazitelné.

Shromažďování trasování ze spuštění aplikace pomocí diagnostického portu

Diagnostický port je funkce modulu runtime přidaná v .NET 5, která umožňuje spustit trasování od spuštění aplikace. K tomu dotnet-tracemůžete použít buď použití dotnet-trace collect -- <command> , jak je popsáno v příkladech výše, nebo použít --diagnostic-port možnost.

Použití dotnet-trace <collect|monitor> -- <command> ke spuštění aplikace jako podřízeného procesu je nejjednodušší způsob, jak rychle trasovat aplikaci od jejího spuštění.

Pokud ale chcete získat přehlednější kontrolu nad životností aplikace, která se sleduje (například monitorujte aplikaci pouze po dobu prvních 10 minut a pokračujte v provádění), nebo pokud potřebujete pracovat s aplikací pomocí rozhraní příkazového řádku, můžete pomocí --diagnostic-port možnosti řídit jak monitorovanou dotnet-tracecílovou aplikaci, tak i .

  1. Následující příkaz vytvoří dotnet-trace diagnostický soket s názvem myport.sock a počká na připojení.

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

    Výstup:

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

  2. V samostatné konzole spusťte cílovou aplikaci s proměnnou DOTNET_DiagnosticPorts prostředí nastavenou na hodnotu ve výstupu dotnet-trace .

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

    To by pak mělo umožnit dotnet-trace spuštění trasování 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.

    Důležité

    Spuštění aplikace dotnet run pomocí aplikace může být problematické, protože rozhraní příkazového řádku dotnet může vytvořit mnoho podřízených procesů, které nejsou vaší aplikací, a můžou se připojit dotnet-trace před aplikací a nechat aplikaci pozastavenou za běhu. Doporučujeme přímo použít samostatnou verzi aplikace nebo ji spustit dotnet exec .

Zobrazení trasování zachyceného z dotnet-trace

Ve Windows můžete zobrazit soubory .nettrace v sadě Visual Studio nebo PerfView pro účely analýzy.

V Linuxu můžete trasování zobrazit změnou výstupního dotnet-trace formátu na speedscope. Pomocí této možnosti změňte formát výstupního -f|--format souboru. Můžete si vybrat mezi nettrace (výchozí možností) a speedscope. Tato možnost -f speedscope vytvoří dotnet-trace speedscope soubor. Speedscope soubory lze otevřít na adrese https://www.speedscope.app.

U trasování shromážděných na platformách jiných než Windows můžete trasovací soubor přesunout do počítače s Windows a zobrazit ho v sadě Visual Studio nebo PerfView.

Poznámka:

Modul runtime .NET Core generuje trasování ve nettrace formátu. Trasování se po dokončení trasování převede na speedscope (pokud je zadáno). Vzhledem k tomu, že některé převody můžou vést ke ztrátě dat, původní nettrace soubor se zachová vedle převedeného souboru.

Použití souboru .rsp k tomu, abyste se vyhnuli psaní dlouhých příkazů

Můžete spustit dotnet-trace soubor .rsp , který obsahuje argumenty, které se mají předat. To může být užitečné při povolování poskytovatelů, kteří očekávají dlouhé argumenty, nebo při použití prostředí prostředí, které odstraní znaky.

Například následující poskytovatel může být těžkopádný k zadání pokaždé, když chcete trasovat:

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

Předchozí příklad navíc obsahuje " jako součást argumentu. Vzhledem k tomu, že uvozovky se nezpracují rovnoměrně v jednotlivých prostředích, můžete při používání různých prostředí zaznamenat různé problémy. Například příkaz, který zsh se má zadat, se liší od příkazu v cmd.

Místo toho, abyste tento text pokaždé zapisovat, můžete uložit následující text do souboru s názvem 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

Po uložení myprofile.rspmůžete s touto konfigurací spustit dotnet-trace pomocí následujícího příkazu:

dotnet-trace @myprofile.rsp

Viz také