Sdílet prostřednictvím

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

Tento článek se vztahuje na: ✔️ dotnet-trace 9.0.661903 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.

  • Podporuje dva různé způsoby shromažďování trasování:

    • Příkaz collect nabízí konzistentní funkce v jakémkoli operačním systému.
    • Příkazcollect-linux používá možnosti operačního systému specifického pro Linux k poskytování dalších funkcí.
    Vlastnost collect collect-linux
    Podporovaný operační systém Jakýkoliv Pouze Linux, verze >jádra = 6.4
    Vyžaduje oprávnění správce nebo kořenového adresáře. Ne Ano
    Trasování všech procesů současně Ne Podporováno
    Zachycení nativních událostí knihovny a jádra Ne Podporováno
    Zásobníky volání událostí zahrnují nativní rámce. Ne Ano

Možnosti

  • -h|--help

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

  • --version

    Zobrazí verzi nástroje dotnet-trace.

Příkazy

Příkaz
dotnet-trace collect
dotnet-trace collect-linux
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>]
    [--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>]

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. Tato možnost se použije pouze v případě, že --clrevents je zadána a není přepsána --profile pomocí nebo --providers. 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. Pokud je poskytovatel modulu runtime Microsoft-Windows-DotNETRuntime CLR povolen také prostřednictvím --providers nebo --profileje tato možnost ignorována. V následující tabulce je seznam dostupných klíčových slov:

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

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

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

    Spustí dotnet-dsrouter a připojí se k němu. Vyžaduje instalaci dotnet-dsrouter . Další informace potřebujete spustit dotnet-dsrouter -h .

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

    Poznámka:

    V Linuxu a macOS vyžaduje použití této možnosti cílovou aplikaci a dotnet-trace sdílení stejné TMPDIR proměnné prostředí. Jinak vyprší časový limit příkazu.

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

    Nastaví diagnostický port používaný ke komunikaci s procesem, který se má trasovat. dotnet-trace a modul runtime .NET v rámci cílového procesu musí souhlasit s adresou portu s jedním nasloucháním a druhým připojením. dotnet-trace automaticky určuje správný port při připojování pomocí --process-id možností nebo --name při spuštění procesu pomocí -- <command> této možnosti. Obvykle je nutné zadat port explicitně při čekání na proces, který se spustí v budoucnu, nebo komunikovat s procesem spuštěným v kontejneru, který není součástí oboru názvů aktuálního procesu.

    Liší se port-address podle operačního systému:

    • Linux a macOS – cesta k soketu domény Unixu, například /foo/tool1.socket.
    • Windows – cesta k pojmenované svislé sadě, například \\.\pipe\my_diag_port1.
    • Android, iOS a tvOS – IP:port, například 127.0.0.1:9000.

    Ve výchozím nastavení dotnet-trace naslouchá na zadané adrese. Místo toho můžete požádat o dotnet-trace připojení připojením ,connect za adresou. Připojí se například --diagnostic-port /foo/tool1.socket,connect k procesu modulu runtime .NET, který naslouchá soketu domény unixu /foo/tool1.socket .

    Pokud chcete zjistit, jak pomocí této možnosti shromáždit trasování ze spuštění aplikace, přečtěte si téma 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.

    Poznámka:

    V Linuxu a macOS vyžaduje použití této možnosti cílovou aplikaci a dotnet-trace sdílení stejné TMPDIR proměnné prostředí. Jinak vyprší časový limit příkazu.

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

    Profil je předdefinovaná sada konfigurací zprostředkovatele pro běžné scénáře trasování. Najednou lze zadat více profilů oddělených čárkami. Zprostředkovatelé nakonfigurovaní prostřednictvím --providers přepsání konfigurace profilu. Podobně pokud některý profil nakonfiguruje zprostředkovatele modulu runtime CLR, přepíše všechny konfigurace předepsané prostřednictvím --clrevents.

    Když --profile, --providersa --clrevents jsou všechny vynechány, dotnet-trace collect povolí profily dotnet-common a dotnet-sampled-thread-time ve výchozím nastavení.

    Dostupné profily:

    Profil Popis
    dotnet-common Zjednodušená diagnostika modulu runtime .NET navržená tak, aby zůstala nízká režie.
    Zahrnuje události GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap a Compilation.
    Ekvivalent k --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Vzorkuje zásobníky vláken .NET (~100 Hz) k identifikaci hotspotů v průběhu času. Používá ukázkový profiler modulu runtime se spravovanými zásobníky.
    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.
    database Zaznamenává ADO.NET a příkazy databáze Entity Framework.

    Poznámka:

    V předchozích verzích nástroje dotnet-trace podporoval příkaz collect název profilu cpu-sampling. Tento profil byl odebrán, protože název byl zavádějící. Vzorkovala všechna vlákna bez ohledu na jejich využití procesoru. Podobný výsledek teď můžete dosáhnout pomocí .--profile dotnet-sampled-thread-time,dotnet-common Pokud potřebujete přesně shodovat s dřívějším cpu-sampling chováním, použijte --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

  • --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 <list-of-comma-separated-profile-names> Pokud je pro konkrétního poskytovatele nějaká nekonzistence, má tato konfigurace přednost před implicitní konfigurací od --profile a --clrevents.

    Tento seznam poskytovatelů je ve formátu Provider[,Provider]:

    • Provider je ve formátu: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs je ve formátu: [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. Pokud chcete například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime zastavit trasování při dosažení první události generované poskytovatelem Microsoft-Windows-DotNETRuntime 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. Pokud chcete například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted zastavit trasování při dosažení první Method/JittingStarted události generované poskytovatelem Microsoft-Windows-DotNETRuntime 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. Chcete-li například --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick zastavit trasování při první Method/JittingStarted události metody OnButtonClick v Program oboru názvů generovaného 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í.
  • 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 collect-linux

Poznámka:

Příkaz collect-linux je nová funkce ve verzi Preview a spoléhá na aktualizovanou verzi formátu souboru .nettrace. Nejnovější verze PerfView podporuje tyto trasovací soubory, ale jiné způsoby použití trasovací soubor, například convert a report, nemusí ještě fungovat.

Shromažďuje diagnostické trasování pomocí perf_events, technologie operačního systému Linux. collect-linux umožňuje následující další funkce v průběhu collect.

Vlastnost collect collect-linux
Podporovaný operační systém Jakýkoliv Pouze Linux, verze >jádra = 6.4
Vyžaduje oprávnění správce nebo kořenového adresáře. Ne Ano
Trasování všech procesů současně Ne Podporováno
Zachycení nativních událostí knihovny a jádra Ne Podporováno
Zásobníky volání událostí zahrnují nativní rámce. Ne Ano

Požadavky

  • Jádro Linuxu s CONFIG_USER_EVENTS=y podporou (jádro 6.4+)
  • Kořenová oprávnění
  • .NET 10+

Poznámka:

Příkaz collect-linux běží jenom v prostředích linux x64 a linux arm64, která mají glibc verze 2.35 nebo vyšší. Všechny distribuce .NET 10 oficiálně podporované linuxovými distribucemi podporují tento požadavek s výjimkou Alpine 3.22, CentOS Stream 9 a všech distribucí založených na Red Hat Enterprise Linuxu 9. Rychlý způsob, jak zkontrolovat verzi libc systému, je příkaz ldd --version nebo spuštění knihovny libc přímo.

Synopse

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]

Výchozí chování kolekce

Pokud --providers, --profile, --clreventsa --perf-events nejsou zadány, collect-linux povolí tyto profily ve výchozím nastavení:

  • dotnet-common – zjednodušená diagnostika modulu runtime .NET.
  • cpu-sampling – vzorkování procesoru jádra.

Ve výchozím nastavení se všechny procesy na počítači trasují. Pokud chcete trasovat pouze jeden proces, použijte -n, --name <name> nebo -p|--process-id <PID>.

Možnosti

Možnosti specifikace poskytovatele nebo události

  • --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 <list-of-comma-separated-profile-names> Pokud je pro konkrétního poskytovatele nějaká nekonzistence, má tato konfigurace přednost před implicitní konfigurací od --profile a --clrevents.

    Tento seznam poskytovatelů je ve formátu Provider[,Provider]:

    • Provider je ve formátu: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs je ve formátu: [key1=value1][;key2=value2]

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

  • --clreventlevel <clreventlevel>

    Úroveň podrobností událostí CLR, které se mají vygenerovat. Tato možnost se použije pouze v případě, že --clrevents je zadána a není přepsána --profile pomocí nebo --providers. 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-linux --providers Microsoft-Windows-DotNETRuntime:3:4 vyžaduje stejnou sadu událostí jako dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Pokud je poskytovatel modulu runtime Microsoft-Windows-DotNETRuntime CLR povolen také prostřednictvím --providers nebo --profileje tato možnost ignorována. V následující tabulce je seznam dostupných klíčových slov:

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

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

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

    Čárkami oddělený seznam událostí výkonu, které se mají zahrnout do trasování. Dostupné události lze najít v trasovacích souborech, které jsou obvykle připojené na /sys/kernel/tracingadrese , prostřednictvím available_events všech dostupných událostí nebo prostřednictvím events/ podadresáře pro události zařazené do kategorií.

    Příklad: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

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

    Profil je předdefinovaná sada konfigurací zprostředkovatele pro běžné scénáře trasování. Najednou lze zadat více profilů oddělených čárkami. Zprostředkovatelé nakonfigurovaní prostřednictvím --providers přepsání konfigurace profilu. Podobně pokud některý profil nakonfiguruje zprostředkovatele modulu runtime CLR, přepíše všechny konfigurace předepsané prostřednictvím --clrevents.

    Když --profile, --providers, --clreventsa jsou všechny --perf-events vynechány, dotnet-trace collect-linux povolí profily dotnet-common a cpu-sampling ve výchozím nastavení.

    Dostupné profily:

    Profil Popis
    dotnet-common Zjednodušená diagnostika modulu runtime .NET navržená tak, aby zůstala nízká režie.
    Zahrnuje události GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap a Compilation.
    Ekvivalent k --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    cpu-sampling Vzorkování procesoru jádra (založené na výkonu) generované jako Universal.Events/cpupro přesné přisuzování procesoru na procesoru.
    thread-time Přepínače kontextu vlákna jádra, které se generují jako Universal.Events/cswitch, pro analýzu on/off-CPU a plánovače.
    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.
    database Zaznamenává ADO.NET a příkazy databáze Entity Framework.

Možnosti kolekce trasování

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

    Výstupní cesta pro shromážděná data trasování. Pokud není zadáno, nastaví se výchozí trace_<yyyyMMdd>_<HHmmss>.nettrace trasování na úrovni počítače a trasování <appname>_<yyyyMMdd>_<HHmmss>.nettrace specifické pro proces (--name nebo --process-id)

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

Možnosti cíle procesu .NET

Zobrazit výchozí chování shromažďování

  • -n, --name <name>

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

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

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

Možnosti režimu sondy

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

    Sonda procesů .NET pro podporu příkazu EventPipe UserEvents IPC, který používá collect-linux, bez shromažďování trasování Seznam výsledků nejprve podporuje procesy. Pomocí příkazu -o stdout vytiskněte soubor CSV (pid, processName, supportsCollectLinux) do konzoly nebo -o output-filename pro zápis souboru CSV. Sonda jednoho procesu pomocí -n|--name nebo -p|--process-id.

    Vzhledem k tomu, že spuštění collect-linux v režimu sondy neshromažďuje trasování, nevyžaduje ke spuštění kořenová oprávnění. Neposkytuje ověření požadavků a procesy .NET spuštěné ve verzích preview modulu .NET Runtime 10.0.0 se považují za nepodporované.

Poznámka:

Pokud chcete shromáždit trasování pomocí dotnet-trace collect-linux, musí se spouštět s oprávněními uživatele root (CAP_PERFMON/CAP_SYS_ADMIN). Jinak nástroj neshromažďuje události.

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

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

    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.

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

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

Trasování můžete zastavit stisknutím nebo <Enter> klávesou<Ctrl + C>. 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 .

(jenom Linux) Shromažďování trasování na úrovni počítače pomocí dotnet-trace

Tento příklad zachycuje ukázky procesoru pro všechny procesy na počítači. Všechny procesy, na kterých běží .NET 10 nebo novější, budou obsahovat také některé další odlehčené události popisující chování načítání GC, JIT a Sestavení.

$ 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

U prostředí s nainstalovanými několika verzemi .NET pomáhá spuštění collect-linux v režimu sondy zjistit, jestli je proces .NET schopný trasovat pomocí collect-linuxu.

$ 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'

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-tracespeedscope 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é

  • Last updated on