nástroj dotnet-trace performance analysis

Tento článek se týká: ✔️ .NET Core 3.0 SDK a novějších verzí

Instalace

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

• dotnet global tool:

  K instalaci nejnovější verze balíčku dotnet-trace NuGet použijtepříkaz dotnet tool install:

  dotnet tool install --global dotnet-trace
  

• Přímé stažení:

  Stáhněte si spustitelný soubor nástroje, který odpovídá vaší platformě:

  Operační systém	Platforma
  Windows	x86 | x64 | arm (arm) | arm-x64
  macOS	x64
  Linux	x64 | arm (arm) | arm64 | musl-x64 | musl-arm64

Synopse

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

Description

dotnet-traceNástroj:

• Je nástroj .NET Core pro více platforem.
• Povolí kolekci trasování .NET Core spuštěného procesu bez nativního profileru.
• Je postaven na EventPipe modulu runtime .NET Core.
• Zajišťuje stejné prostředí v Windows, Linuxu nebo macOS.

Možnosti

• -h|--help

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

• --version

  Zobrazí verzi nástroje dotnet-trace.

Příkazy

dotnet-trace collect

Shromažďuje diagnostické trasování ze spuštěného procesu nebo spustí podřízený proces a trasuje ho (pouze .NET 5+). Pokud chcete, aby nástroj spouštěl podřízený proces a trasoval ho od 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]
    [-n, --name <name>] [--diagnostic-port] [-o|--output <trace-file-path>] [-p|--process-id <pid>]
    [--profile <profile-name>] [--providers <list-of-comma-separated-providers>]
    [--show-child-io]
    [-- <command>] (for target applications running .NET 5 or later)

Možnosti

• --buffersize <size>

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

  Poznámka

  Pokud cílový proces zapisuje události příliš často, může tuto vyrovnávací paměť přetéct a některé události můžou být zahozeny. Pokud dochází k vyřazení příliš velikosti událostí, zvětšete velikost vyrovnávací paměti, abyste viděli, jestli se počet vyřazených událostí sníží. Pokud se počet vyřazených událostí s větší velikostí vyrovnávací paměti nesnítí, může to být způsobeno pomalým čtenářem, který brání vyprázdnění vyrovnávacích pamětí cílového procesu.

• --clreventlevel <clreventlevel>

  Podrobné informace o událostech CLR, které se budou generovat.

• --clrevents <clrevents>

  Seznam klíčových slov zprostředkovatele modulu runtime MODULU CLR, aby bylo možné je oddělit + znaky. Toto je jednoduché mapování, které umožňuje zadat klíčová slova událostí prostřednictvím aliasů řetězců místo šestnáctových hodnot. Například dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 vyžádá stejnou sadu událostí jako dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational . Následující tabulka obsahuje seznam dostupných klíčových slov:

  Alias řetězce klíčového slova	Šestnáctková 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

  Podrobnější informace o poskytovateli modulu CLR najdete v referenční dokumentaci k poskytovateli modulu runtime .NET.

• --format {Chromium|NetTrace|Speedscope}

  Nastaví výstupní formát pro převod trasovacího souboru. Výchozí formát je NetTrace.

• -n, --name <name>

  Název procesu, ze které se má trasování shromažďovat.

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

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

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

  Výstupní cesta pro shromážděná data trasování. Pokud není zadaný, výchozí hodnota je trace.nettrace .

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

  ID procesu, ze které se má trasování shromažďovat.

• --profile <profile-name>

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

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

  Seznam poskytovatelů oddělených EventPipe čárkami, které se mají povolit. Tito poskytovatelé doplňují všechny poskytovatele, které implikuje --profile <profile-name> . Pokud u určitého zprostředkovatele dojde k nějaké nekonzistence, má tato konfigurace přednost před implicitní konfigurací z profilu.

  Tento seznam zprostředkovatelů má následující podobu:

  • Provider[,Provider]
  • Provider má tvar: KnownProviderName[:Flags[:Level][:KeyValueArgs]] .
  • KeyValueArgs má tvar: [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í.

• -- <command> (jenom pro cílové aplikace s .NET 5)

  Po parametrech konfigurace kolekce může uživatel připojit následovaný příkazem, který spustí aplikaci .NET s minimálně -- 5.0 runtime. To může být užitečné při diagnostice problémů, ke které dochází v rané fázi procesu, jako je například problém s výkonem při spuštění nebo chyby zavaděče sestavení a vázání.

  Poznámka

  Tato možnost monitoruje první proces rozhraní .NET 5, který komunikuje zpět s nástrojem, což znamená, že pokud příkaz spustí více aplikací .NET, shromáždí pouze první aplikaci. Proto doporučujeme použít tuto možnost u samostatných aplikací nebo pomocí 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.

dotnet-trace convert

Převede trasování nettrace do alternativních formátů pro použití s alternativními nástroji pro analýzu 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ího souboru.

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

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

dotnet-trace ps

Obsahuje seznam procesů dotnet, ze které je možné shromažďovat trasování.

Synopse

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

dotnet-trace list-profiles

Uvádí předem vytvořené profily trasování s popisem poskytovatelů a filtrů v jednotlivých profilech.

Synopse

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

Shromažďová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í.

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

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

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

  Předchozí příkaz vygeneruje 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)
  

• Stisknutím klávesy zastavte <Enter> shromažďování. dotnet-tracedokončí 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í příkazu dotnet-trace

Někdy může být užitečné shromáždit trasování procesu z jeho spuštění. U aplikací se systémem .NET 5 nebo novějším je možné to provést pomocí příkazu dotnet-trace.

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

dotnet-trace collect -- hello.exe arg1 arg2

Předchozí příkaz vygeneruje 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...

Shromažďování trasování můžete zastavit stisknutím <Enter> klávesy <Ctrl + C> nebo . Tím také ukončíte hello.exe příkaz .

Použití diagnostického portu ke shromažďování trasování ze spuštění aplikace

Diagnostický port je nová funkce modulu runtime, která byla přidána do rozhraní .NET 5 a umožňuje spustit trasování ze spuštění aplikace. Pokud to chcete provést dotnet-trace pomocí , můžete použít buď , jak je popsáno v dotnet-trace collect -- <command> příkladech výše, nebo použít --diagnostic-port možnost .

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

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

1. Následující příkaz vytvoří dotnet-trace diagnostický soket s názvem a myport.sock 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 prostředí nastavenou DOTNET_DiagnosticPorts na hodnotu ve dotnet-trace výstupu.

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

   Tím by se mělo povolit dotnet-trace spuštění my-dotnet-app trasování:

   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 pomocí 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 mohou se připojit k před vaší aplikací a nechat aplikaci pozastavenou dotnet run dotnet-trace za běhu. Doporučuje se použít přímo samostatnou verzi aplikace nebo použít ke dotnet exec spuštění aplikace.

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

V Windows nástroje PerfView je možné zobrazit soubory .nettrace pro analýzu: V případě trasování shromážděných na jiných platformách je možné trasovací soubor přesunout na počítač Windows, který chcete zobrazit v nástroji PerfView.

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

Použití dotnet-trace ke shromažďování hodnot čítačů v průběhu času

dotnet-trace Cna:

• Slouží EventCounter k základnímu monitorování stavu v prostředích citlivých na výkon. Například v produkčním prostředí.
• Shromáždí trasování, aby se v reálném čase nemusí prohlížet.

Pokud například chcete shromažďovat hodnoty čítače výkonu modulu runtime, použijte následující příkaz:

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

Předchozí příkaz říká čítačům modulu runtime, aby každou sekundu hlásit zjednodušené monitorování stavu. Nahrazení EventCounterIntervalSec=1 vyšší hodnotou (například 60) umožňuje shromažďování menšího trasování s menší členitostí v datech čítače.

Následující příkaz snižuje režii a velikost trasování více než předchozí příkaz:

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

Předchozí příkaz zakáže události modulu runtime a profiler spravovaného zásobníku.

Pokud se chcete vyhnout psaní dlouhých příkazů, použijte soubor .rsp.

Můžete spustit dotnet-trace se .rsp souborem, který obsahuje argumenty, které se mají předat. To může být užitečné při povolování zprostředkovatelů, kteří očekávají dlouhé argumenty, nebo při použití prostředí, které prokládá 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

Kromě toho předchozí příklad obsahuje " jako součást argumentu . Vzhledem k tomu, že uvozovky nejsou zpracovávány stejným způsobem v jednotlivých prostředích, může při použití různých prostředí dojít k různým problémům. Například příkaz pro zadání se zsh liší od příkazu v souboru cmd .

Místo toho, abyste tento text zadávat pokaždé, 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í můžete spustit myprofile.rsp s touto konfigurací pomocí dotnet-trace následujícího příkazu:

dotnet-trace @myprofile.rsp

Viz také

• Známí zprostředkovatelé událostí z .NET