dotnet-trace performance analysis utility (narzędzie do analizy wydajności dotnet-trace)

Ten artykuł dotyczy: ✔️ dotnet-trace 9.0.661903 i nowszych wersji

Instalowanie

Istnieją dwa sposoby pobierania i instalowania dotnet-traceprogramu :

• dotnet global tool (narzędzie globalne dotnet):

  Aby zainstalować najnowszą wersję dotnet-tracepakietu NuGet, użyj polecenia dotnet tool install :

  dotnet tool install --global dotnet-trace
  

• Pobieranie bezpośrednie:

  Pobierz plik wykonywalny narzędzia pasujący do platformy:

  System operacyjny	Platforma
  Windows	x86 | x64 | Arm | Arm-x64
  Linuxa	|

Streszczenie

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

opis

Narzędzie dotnet-trace :

• To międzyplatformowe narzędzie .NET Core.

• Umożliwia zbieranie śladów platformy .NET Core działającego procesu bez natywnego profilera.

• Jest oparty na EventPipe środowisku uruchomieniowym platformy .NET Core.

• Obsługuje dwa różne sposoby zbierania śladów:

  • Czasownik collect oferuje spójne funkcje w dowolnym systemie operacyjnym.
  • Czasownik collect-linux używa funkcji systemu operacyjnego specyficznego dla systemu Linux w celu zapewnienia dodatkowych funkcji.

  Funkcja	collect	collect-linux
  Obsługiwany system operacyjny	Jakikolwiek	Tylko linux, wersja >jądra = 6.4
  Wymaga uprawnień administratora/głównego	Nie.	Tak
  Śledzenie wszystkich procesów jednocześnie	Nie.	Wsparte
  Przechwytywanie zdarzeń biblioteki natywnej i jądra	Nie.	Wsparte
  Stosy wywołań zdarzeń obejmują ramki natywne	Nie.	Tak

Opcje

• -h|--help

  Pokazuje pomoc wiersza polecenia.

• --version

  Wyświetla wersję narzędzia dotnet-trace.

Polecenia

Polecenie
dotnet-trace collect
dotnet-trace collect-linux
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace report

dotnet-trace collect

Zbiera ślad diagnostyczny z uruchomionego procesu lub uruchamia proces podrzędny i śledzi go (.NET 5 lub nowszy). Aby narzędzie uruchamiało proces podrzędny i śledziło go z jego uruchamiania, dołącz -- go do polecenia collect.

Streszczenie

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

Opcje

• --buffersize <size>

  Ustawia rozmiar buforu w pamięci w megabajtach. Domyślnie 256 MB.

  Uwaga

  Jeśli proces docelowy emituje zdarzenia szybciej niż można je zapisać na dysku, ten bufor może przepełnić się i niektóre zdarzenia zostaną porzucone. Ten problem można rozwiązać, zwiększając rozmiar buforu lub zmniejszając liczbę rejestrowanych zdarzeń.

• --clreventlevel <clreventlevel>

  Szczegółowość zdarzeń CLR, które mają być emitowane. Ta opcja ma zastosowanie tylko wtedy, gdy --clrevents jest określona i nie jest zastępowana przez --profile lub --providers. W poniższej tabeli przedstawiono dostępne poziomy zdarzeń.

  Wartość ciągu	Wartość liczbowa
  logalways	0
  critical	1
  error	2
  warning	3
  informational	4
  verbose	5

• --clrevents <clrevents>

  Lista słów kluczowych dostawcy środowiska uruchomieniowego CLR w celu włączenia rozdzielonych znakami + . Jest to proste mapowanie, które umożliwia określenie słów kluczowych zdarzeń za pośrednictwem aliasów ciągów, a nie ich wartości szesnastkowych. Na przykład dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 żąda tego samego zestawu zdarzeń co dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Jeśli dostawca Microsoft-Windows-DotNETRuntime środowiska uruchomieniowego CLR jest również włączony za pośrednictwem --providers lub --profile, ta opcja jest ignorowana. W poniższej tabeli przedstawiono listę dostępnych słów kluczowych:

  Alias ciągu słowa kluczowego	Wartość szesnastkowy słowa kluczowego
  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

  Więcej informacji na temat dostawcy CLR można uzyskać w dokumentacji referencyjnej dostawcy środowiska uruchomieniowego platformy .NET.

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

  Uruchamia narzędzie dotnet-dsrouter i nawiązuje z nim połączenie. Wymaga zainstalowania narzędzia dotnet-dsrouter . Uruchom polecenie dotnet-dsrouter -h , aby uzyskać więcej informacji.

• --format {Chromium|NetTrace|Speedscope}

  Ustawia format danych wyjściowych konwersji pliku śledzenia. Wartość domyślna to NetTrace.

• -n, --name <name>

  Nazwa procesu do zbierania śladu.

  Uwaga

  W systemach Linux i macOS użycie tej opcji wymaga aplikacji docelowej i dotnet-trace współużytkowania tej samej TMPDIR zmiennej środowiskowej. W przeciwnym razie upłynął limit czasu polecenia.

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

  Ustawia port diagnostyczny używany do komunikowania się z procesem do śledzenia. dotnet-trace i środowisko uruchomieniowe platformy .NET wewnątrz procesu docelowego muszą uzgodnić adres-port z jednym nasłuchiwaniem i drugim połączeniem. dotnet-trace automatycznie określa prawidłowy port podczas dołączania przy użyciu --process-id opcji lub --name lub podczas uruchamiania -- <command> procesu przy użyciu opcji . Zazwyczaj konieczne jest jawne określenie portu podczas oczekiwania na proces, który rozpocznie się w przyszłości lub komunikowanie się z procesem uruchomionym wewnątrz kontenera, który nie jest częścią bieżącej przestrzeni nazw procesów.

  Różnią się w port-address zależności od systemu operacyjnego:

  • Linux i macOS — ścieżka do gniazda domeny systemu Unix, takiego jak /foo/tool1.socket.
  • Windows — ścieżka do nazwanego potoku, takiego jak \\.\pipe\my_diag_port1.
  • Android, iOS i tvOS — port IP:, taki jak 127.0.0.1:9000.

  Domyślnie dotnet-trace nasłuchuje pod określonym adresem. Zamiast tego możesz zażądać dotnet-trace połączenia, dołączając ,connect go po adresie. Na przykład --diagnostic-port /foo/tool1.socket,connect nawiąż połączenie z procesem środowiska uruchomieniowego platformy .NET, który nasłuchuje /foo/tool1.socket gniazda domeny systemu Unix.

  Aby dowiedzieć się, jak używać tej opcji do zbierania śladu z uruchamiania aplikacji, zobacz Używanie portu diagnostycznego do zbierania śladu po uruchomieniu aplikacji.

• --duration <time-to-run>

  Czas uruchomienia śledzenia. dd:hh:mm:ss Użyj formatu. Na przykład 00:00:00:05 uruchomi go przez 5 sekund.

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

  Ścieżka wyjściowa dla zebranych danych śledzenia. Jeśli nie określono wartości domyślnej <appname>_<yyyyMMdd>_<HHmmss>.nettrace, na przykład "myapp_20210315_111514.nettrace".

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

  Identyfikator procesu do zbierania śladu.

  Uwaga

  W systemach Linux i macOS użycie tej opcji wymaga aplikacji docelowej i dotnet-trace współużytkowania tej samej TMPDIR zmiennej środowiskowej. W przeciwnym razie upłynął limit czasu polecenia.

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

  Profil to wstępnie zdefiniowany zestaw konfiguracji dostawcy dla typowych scenariuszy śledzenia. Jednocześnie można określić wiele profilów rozdzielonych przecinkami. Dostawcy skonfigurowani przez --providers zastąpienie konfiguracji profilu. Podobnie, jeśli jakikolwiek profil konfiguruje dostawcę środowiska uruchomieniowego CLR, zastąpi wszystkie konfiguracje określone za pomocą polecenia --clrevents.

  Gdy --profilewszystkie elementy , --providersi --clrevents zostaną pominięte, dotnet-trace collect włącza profile dotnet-common i dotnet-sampled-thread-time domyślnie.

  Dostępne profile:

  Profil	opis
  dotnet-common	Uproszczona diagnostyka środowiska uruchomieniowego platformy .NET zaprojektowana w celu utrzymania niskich obciążeń. Obejmuje zdarzenia GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap i Kompilacja Odpowiednik --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
  dotnet-sampled-thread-time	Przykłady stosów wątków platformy .NET (~100 Hz) w celu identyfikowania hotspotów w czasie. Używa przykładowego profilera środowiska uruchomieniowego z zarządzanymi stosami.
  gc-verbose	Śledzi kolekcje GC i przykłady alokacji obiektów.
  gc-collect	Śledzi kolekcje GC tylko przy bardzo niskim narzucie.
  database	Przechwytuje ADO.NET i polecenia bazy danych programu Entity Framework.

  Uwaga

  W poprzednich wersjach narzędzia dotnet-trace czasownik collect obsługiwał profil o nazwie cpu-sampling. Ten profil został usunięty, ponieważ nazwa była myląca. Próbkowane wszystkie wątki niezależnie od użycia procesora CPU. Możesz teraz osiągnąć podobny wynik przy użyciu polecenia --profile dotnet-sampled-thread-time,dotnet-common. Jeśli musisz dokładnie dopasować poprzednie cpu-sampling zachowanie, użyj polecenia --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

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

  Rozdzielona przecinkami lista EventPipe dostawców do włączenia. Ci dostawcy uzupełniają wszystkich dostawców sugerowanych przez --profile <list-of-comma-separated-profile-names>usługę . Jeśli istnieje niespójność dla określonego dostawcy, ta konfiguracja ma pierwszeństwo przed niejawną konfiguracją z --profile i --clrevents.

  Ta lista dostawców ma postać Provider[,Provider]:

  • Provider ma postać: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
  • KeyValueArgs ma postać: [key1=value1][;key2=value2]

  Aby dowiedzieć się więcej na temat niektórych znanych dostawców na platformie .NET, zapoznaj się z tematem Dobrze znani dostawcy zdarzeń.

• -- <command> (dla aplikacji docelowych z systemem .NET 5 lub nowszym)

  Po parametrach konfiguracji kolekcji użytkownik może dołączyć -- następujące polecenie, aby uruchomić aplikację platformy .NET z co najmniej środowiskiem uruchomieniowym 5.0. Może to być przydatne podczas diagnozowania problemów występujących na wczesnym etapie procesu, takich jak problem z wydajnością uruchamiania lub błędy modułu ładującego zestawów i binder.

  Uwaga

  Użycie tej opcji monitoruje pierwszy proces platformy .NET, który komunikuje się z powrotem do narzędzia, co oznacza, że jeśli polecenie uruchamia wiele aplikacji platformy .NET, będzie zbierać tylko pierwszą aplikację. W związku z tym zaleca się użycie tej opcji w aplikacjach samodzielnie lub przy użyciu dotnet exec <app.dll> opcji .

• --show-child-io

  Przedstawia strumienie wejściowe i wyjściowe uruchomionego procesu podrzędnego w bieżącej konsoli.

• --resume-runtime

  Wznów środowisko uruchomieniowe po zainicjowaniu sesji, domyślnie ma wartość true. Wyłącz wznawianie środowiska uruchomieniowego przy użyciu polecenia --resume-runtime:false.

• --stopping-event-provider-name

  Ciąg, analizowany tak, jak to jest, który zatrzyma śledzenie po osiągnięciu zdarzenia z zgodną nazwą dostawcy. W przypadku bardziej szczegółowego zdarzenia zatrzymania podaj i --stopping-event-event-name /lub --stopping-event-payload-filter. na przykład aby --stopping-event-provider-name Microsoft-Windows-DotNETRuntime zatrzymać śledzenie po osiągnięciu pierwszego zdarzenia emitowanego przez dostawcę Microsoft-Windows-DotNETRuntime zdarzeń.

• --stopping-event-event-name

  Ciąg, analizowany w stanie takim, w jakim jest, spowoduje zatrzymanie śledzenia po osiągnięciu zdarzenia z pasującą nazwą zdarzenia. Wymaga --stopping-event-provider-name ustawienia. Aby uzyskać bardziej szczegółowe zdarzenie zatrzymania, dodatkowo podaj wartość --stopping-event-payload-filter. na przykład aby --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted zatrzymać śledzenie po osiągnięciu pierwszego Method/JittingStarted zdarzenia emitowanego przez dostawcę Microsoft-Windows-DotNETRuntime zdarzeń.

• --stopping-event-payload-filter

  Ciąg, analizowany jako [payload_field_name]:[payload_field_value] par oddzielone przecinkami, które zatrzymają śledzenie po osiągnięciu zdarzenia zawierającego wszystkie określone pary ładunków. Wymaga --stopping-event-provider-name i --stopping-event-event-name należy ustawić. na przykład, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick aby zatrzymać śledzenie po pierwszym Method/JittingStarted zdarzeniu dla metody OnButtonClick w Program przestrzeni nazw emitowanych przez dostawcę Microsoft-Windows-DotNETRuntime zdarzeń.

Uwaga

• Zatrzymanie śledzenia może potrwać długo (do minut) w przypadku dużych aplikacji. Środowisko uruchomieniowe musi wysłać pamięć podręczną typu dla całego kodu zarządzanego przechwyconego w śladzie.

• Aby zebrać dane śledzenia przy użyciu polecenia dotnet-trace, należy uruchomić go jako ten sam użytkownik, co użytkownik, który uruchamia proces docelowy lub jako główny. W przeciwnym razie narzędzie nie może nawiązać połączenia z procesem docelowym.

• Jeśli podczas uruchamiania dotnet-trace collectwystąpi nieobsługiwany wyjątek , spowoduje to niekompletne śledzenie. Jeśli znalezienie głównej przyczyny wyjątku jest twoim priorytetem, przejdź do sekcji Zbieranie zrzutów w przypadku awarii. W wyniku nieobsługiwanego wyjątku ślad jest obcięty, gdy środowisko uruchomieniowe zostanie zamknięte, aby zapobiec inne niepożądanemu zachowaniu, takie jak zawieszenie lub uszkodzenie danych. Mimo że ślad jest niekompletny, nadal można go otworzyć, aby zobaczyć, co się stało, co doprowadziło do awarii. Jednak brakuje informacji rundown (dzieje się to na końcu śledzenia), więc stosy mogą być nierozwiązane (w zależności od tego, którzy dostawcy zostali włączeni). Otwórz ślad, wykonując narzędzie PerfView z flagą /ContinueOnError w wierszu polecenia. Dzienniki będą również zawierać lokalizację, w ramach którego został wyzwolony wyjątek.

• Podczas określania zdarzenia zatrzymania za pośrednictwem --stopping-event-* opcji, ponieważ strumień zdarzeń jest analizowany asynchronicznie, między czasem zdarzenie śledzenia zgodne z określonymi opcjami zdarzenia zatrzymania jest analizowane, a zdarzenie EventPipeSession zostanie zatrzymane.

dotnet-trace collect-linux

Uwaga

Czasownik collect-linux jest nową funkcją w wersji zapoznawczej i opiera się na zaktualizowanej wersji formatu pliku .nettrace. Najnowsza wersja programu PerfView obsługuje te pliki śledzenia, ale inne sposoby korzystania z pliku śledzenia, takie jak convert i report, mogą jeszcze nie działać.

Zbiera ślady diagnostyczne przy użyciu perf_events, technologii systemu operacyjnego Linux. collect-linux program włącza następujące dodatkowe funkcje za pośrednictwem collectprogramu .

Funkcja	collect	collect-linux
Obsługiwany system operacyjny	Jakikolwiek	Tylko linux, wersja >jądra = 6.4
Wymaga uprawnień administratora/głównego	Nie.	Tak
Śledzenie wszystkich procesów jednocześnie	Nie.	Wsparte
Przechwytywanie zdarzeń biblioteki natywnej i jądra	Nie.	Wsparte
Stosy wywołań zdarzeń obejmują ramki natywne	Nie.	Tak

Wymagania wstępne

• Jądro systemu Linux z obsługą CONFIG_USER_EVENTS=y (jądro 6.4 lub nowsze)
• Uprawnienia główne
• .NET 10+

Uwaga

Czasownik collect-linux działa tylko w środowiskach linux x64 i linux arm64, które mają glibc w wersji 2.35 lub nowszej. Wszystkie oficjalnie obsługiwane dystrybucje systemu Linux na platformie .NET 10 obsługują to wymaganie, z wyjątkiem Alpine 3.22, CentOS Stream 9 i wszystkich dystrybucji opartych na systemie Red Hat Enterprise Linux 9. Szybkim sposobem sprawdzenia wersji biblioteki systemu jest użycie polecenia ldd --version lub bezpośrednie wykonanie biblioteki libc.

Streszczenie

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]

Domyślne zachowanie kolekcji

Gdy --providerswartości , --profile, --clreventsi --perf-events nie są określone, collect-linux domyślnie włącza te profile:

• dotnet-common — uproszczona diagnostyka środowiska uruchomieniowego platformy .NET.
• cpu-sampling — próbkowanie procesora CPU jądra.

Domyślnie wszystkie procesy na maszynie są śledzone. Aby śledzić tylko jeden proces, użyj polecenia -n, --name <name> lub -p|--process-id <PID>.

Opcje

Opcje specyfikacji dostawcy/zdarzenia

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

  Rozdzielona przecinkami lista EventPipe dostawców do włączenia. Ci dostawcy uzupełniają wszystkich dostawców sugerowanych przez --profile <list-of-comma-separated-profile-names>usługę . Jeśli istnieje niespójność dla określonego dostawcy, ta konfiguracja ma pierwszeństwo przed niejawną konfiguracją z --profile i --clrevents.

  Ta lista dostawców ma postać Provider[,Provider]:

  • Provider ma postać: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
  • KeyValueArgs ma postać: [key1=value1][;key2=value2]

  Aby dowiedzieć się więcej na temat niektórych znanych dostawców na platformie .NET, zobacz Dobrze znani dostawcy zdarzeń.

• --clreventlevel <clreventlevel>

  Szczegółowość zdarzeń CLR, które mają być emitowane. Ta opcja ma zastosowanie tylko wtedy, gdy --clrevents jest określona i nie jest zastępowana przez --profile lub --providers. W poniższej tabeli przedstawiono dostępne poziomy zdarzeń.

  Wartość ciągu	Wartość liczbowa
  logalways	0
  critical	1
  error	2
  warning	3
  informational	4
  verbose	5

• --clrevents <clrevents>

  Lista słów kluczowych dostawcy środowiska uruchomieniowego CLR w celu włączenia rozdzielonych znakami + . Jest to proste mapowanie, które umożliwia określenie słów kluczowych zdarzeń za pośrednictwem aliasów ciągów, a nie ich wartości szesnastkowych. Na przykład dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 żąda tego samego zestawu zdarzeń co dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Jeśli dostawca Microsoft-Windows-DotNETRuntime środowiska uruchomieniowego CLR jest również włączony za pośrednictwem --providers lub --profile, ta opcja jest ignorowana. W poniższej tabeli przedstawiono listę dostępnych słów kluczowych:

  Alias ciągu słowa kluczowego	Wartość szesnastkowy słowa kluczowego
  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

  Więcej informacji na temat dostawcy CLR można uzyskać w dokumentacji referencyjnej dostawcy środowiska uruchomieniowego platformy .NET.

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

  Rozdzielona przecinkami lista zdarzeń wydajności do uwzględnienia w śladzie. Dostępne zdarzenia można znaleźć w obszarze tracefs, który jest zwykle instalowany w /sys/kernel/tracingprogramie za pośrednictwem available_events dla wszystkich dostępnych zdarzeń lub za pośrednictwem podkatalogu events/ dla zdarzeń podzielonych na kategorie.

  Przykład: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

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

  Profil to wstępnie zdefiniowany zestaw konfiguracji dostawcy dla typowych scenariuszy śledzenia. Jednocześnie można określić wiele profilów rozdzielonych przecinkami. Dostawcy skonfigurowani przez --providers zastąpienie konfiguracji profilu. Podobnie, jeśli jakikolwiek profil konfiguruje dostawcę środowiska uruchomieniowego CLR, zastąpi wszystkie konfiguracje określone za pomocą polecenia --clrevents.

  Gdy --profilewszystkie elementy , --providers, --clreventsi --perf-events zostaną pominięte, dotnet-trace collect-linux włącza profile dotnet-common i cpu-sampling domyślnie.

  Dostępne profile:

  Profil	opis
  dotnet-common	Uproszczona diagnostyka środowiska uruchomieniowego platformy .NET zaprojektowana w celu utrzymania niskich obciążeń. Obejmuje zdarzenia GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap i Kompilacja Odpowiednik --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
  cpu-sampling	Próbkowanie procesora CPU jądra (oparte na wydajności), emitowane jako Universal.Events/cpu, w celu dokładnego przypisania procesora CPU.
  thread-time	Przełączniki kontekstowe wątku jądra, emitowane jako Universal.Events/cswitch, dla analizy włączonej/wyłączonej i harmonogramu.
  gc-verbose	Śledzi kolekcje GC i przykłady alokacji obiektów.
  gc-collect	Śledzi kolekcje GC tylko przy bardzo niskim narzucie.
  database	Przechwytuje ADO.NET i polecenia bazy danych programu Entity Framework.

Opcje zbierania śladów

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

  Ścieżka wyjściowa dla zebranych danych śledzenia. Jeśli nie zostanie określony, domyślnie trace_<yyyyMMdd>_<HHmmss>.nettrace dla domyślnego śledzenia całego komputera i dla <appname>_<yyyyMMdd>_<HHmmss>.nettrace śledzenia specyficznego dla procesu (--name lub --process-id)

• --duration <time-to-run>

  Czas uruchomienia śledzenia. dd:hh:mm:ss Użyj formatu. Na przykład 00:00:00:05 uruchomi go przez 5 sekund.

Opcje docelowe procesu platformy .NET

Zobacz Domyślne zachowanie kolekcji

• -n, --name <name>

  Nazwa procesu do zbierania śladu.

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

  Identyfikator procesu do zbierania śladu.

Opcje trybu sondowania

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

  Sondowanie procesów platformy .NET pod kątem obsługi polecenia IPC EventPipe UserEvents używanego przez collect-linux bez zbierania śladu. Najpierw lista wyników zawiera listę obsługiwanych procesów. Użyj polecenia "-o stdout", aby wydrukować plik CSV (pid,processName,supportsCollectLinux) do konsoli lub "-o output-filename", aby zapisać plik CSV. Sonduj pojedynczy proces z -n|-name lub -p|--process-id.

  Ponieważ uruchamianie collect-linux w trybie sondowania nie zbiera śladu, nie wymaga uprawnień administratora do uruchomienia. Nie zapewnia weryfikacji wymagań wstępnych, a procesy platformy .NET działające w wersjach zapoznawczych środowiska uruchomieniowego .NET Runtime "10.0.0" są uznawane za nieobsługiwane.

Uwaga

Aby zebrać dane śledzenia przy użyciu polecenia dotnet-trace collect-linux, należy go uruchomić z uprawnieniami głównymi (CAP_PERFMON/CAP_SYS_ADMIN). W przeciwnym razie narzędzie nie będzie zbierać zdarzeń.

dotnet-trace convert

Konwertuje nettrace ślady na alternatywne formaty do użycia z alternatywnymi narzędziami do analizy śledzenia.

Streszczenie

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

Argumenty

• <input-filename>

  Plik śledzenia danych wejściowych do przekonwertowania. Wartość domyślna to trace.nettrace.

Opcje

• --format <Chromium|NetTrace|Speedscope>

  Ustawia format danych wyjściowych konwersji pliku śledzenia.

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

  Nazwa pliku wyjściowego. Zostanie dodane rozszerzenie formatu docelowego.

Uwaga

Konwertowanie nettrace plików na chromium pliki lub speedscope jest nieodwracalne. speedscope pliki i chromium nie mają wszystkich informacji niezbędnych do odtworzenia nettrace plików. convert Jednak polecenie zachowuje oryginalny nettrace plik, więc nie usuwaj tego pliku, jeśli planujesz go otworzyć w przyszłości.

dotnet-trace ps

Wyświetla listę procesów dotnet, z których można zbierać ślady. dotnet-trace 6.0.320703 i nowsze, wyświetla również argumenty wiersza polecenia, z którymi uruchomiono każdy proces, jeśli jest dostępny.

Uwaga

Aby uzyskać pełne informacje na temat wyliczanych procesów 64-bitowych, należy użyć 64-bitowej wersji dotnet-trace narzędzia.

Streszczenie

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

Przykład

Załóżmy, że uruchamiasz długotrwałą aplikację przy użyciu polecenia dotnet run --configuration Release. W innym oknie uruchomisz dotnet-trace ps polecenie . Dane wyjściowe, które zobaczysz, są następujące. Argumenty wiersza polecenia, jeśli są dostępne, są wyświetlane w dotnet-trace wersji 6.0.320703 lub nowszej.

> 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

Wyświetla listę wstępnie utworzonych profilów śledzenia z opisem dostawców i filtrów w każdym profilu.

Streszczenie

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

dotnet-trace report

Tworzy raport na podstawie wcześniej wygenerowanego śladu.

Streszczenie

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

Argumenty

• <tracefile>

  Ścieżka pliku do analizowanego śledzenia.

Polecenia

dotnet-trace report topN

Znajduje n najlepszych metod, które były na stosie wywołań najdłużej.

Streszczenie

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

Opcje

• -n|--number <n>

Udostępnia n najlepszych metod na stosie wywołań.

• --inclusive

Wyprowadź pierwsze N metod na podstawie czasu inkluzywnego . Jeśli nie zostanie określony, czas wyłączny jest używany domyślnie.

• -v|--verbose

Wyprowadź pełne parametry każdej metody. Jeśli nie zostanie określony, parametry zostaną obcięte.

Zbieranie śladu za pomocą polecenia dotnet-trace

Aby zebrać ślady przy użyciu polecenia dotnet-trace collect:

• Pobierz identyfikator procesu (PID) aplikacji .NET Core w celu zbierania śladów.

  • W systemie Windows można użyć Menedżera zadań lub tasklist polecenia, na przykład.
  • Na przykład ps w systemie Linux polecenie .
  • dotnet-trace ps

• Uruchom następujące polecenie:

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

  Poprzednie polecenie generuje dane wyjściowe podobne do następujących:

  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.
  

• Zatrzymaj zbieranie, naciskając Enter . dotnet-trace spowoduje zakończenie rejestrowania zdarzeń do .nettrace pliku.

Uruchamianie aplikacji podrzędnej i zbieranie śladu z jego uruchamiania przy użyciu polecenia dotnet-trace

Czasami przydatne może być zebranie śladu procesu od jego uruchomienia. W przypadku aplikacji z systemem .NET 5 lub nowszym można to zrobić przy użyciu polecenia dotnet-trace.

Spowoduje to uruchomienie hello.exearg1 polecenia i arg2 jako argumentów wiersza polecenia i zebranie śladu z uruchomienia środowiska uruchomieniowego:

dotnet-trace collect -- hello.exe arg1 arg2

Poprzednie polecenie generuje dane wyjściowe podobne do następujących:

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

Zbieranie śladu można zatrzymać, naciskając <Enter> lub <Ctrl + C> . Spowoduje to również zakończenie hello.exedziałania .

Uwaga

hello.exe Uruchomienie za pomocą polecenia dotnet-trace spowoduje przekierowanie jego danych wejściowych/wyjściowych i domyślnie nie będzie można z nią korzystać w konsoli. Użyj przełącznika, aby wchodzić w interakcję --show-child-io z elementem stdin/stdout. Zamknięcie narzędzia za pomocą CTRL+C lub SIGTERM bezpiecznie zakończy zarówno narzędzie, jak i proces podrzędny. Jeśli proces podrzędny zakończy się przed narzędziem, narzędzie zakończy działanie, a ślad powinien być bezpiecznie wyświetlany.

Używanie portu diagnostycznego do zbierania śladu z uruchamiania aplikacji

Port diagnostyczny to funkcja środowiska uruchomieniowego dodana na platformie .NET 5, która umożliwia rozpoczęcie śledzenia od uruchamiania aplikacji. Aby to zrobić, dotnet-tracemożesz użyć metody zgodnie z dotnet-trace collect -- <command> opisem w powyższych przykładach lub użyć --diagnostic-port opcji .

Użycie dotnet-trace <collect|monitor> -- <command> polecenia w celu uruchomienia aplikacji jako procesu podrzędnego jest najprostszym sposobem szybkiego śledzenia aplikacji od jej uruchomienia.

Jeśli jednak chcesz uzyskać dokładnszą kontrolę nad okresem istnienia śledzonej aplikacji (na przykład monitorować aplikację tylko przez pierwsze 10 minut i kontynuować wykonywanie) lub jeśli musisz wchodzić w interakcję z aplikacją przy użyciu interfejsu wiersza polecenia, za pomocą --diagnostic-port opcji możesz kontrolować zarówno monitorowaną aplikację docelową, jak i dotnet-trace.

1. Poniższe polecenie powoduje dotnet-trace utworzenie gniazda diagnostycznego o nazwie myport.sock i oczekiwanie na połączenie.

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

   Wyjście:

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

2. W oddzielnej konsoli uruchom aplikację docelową ze zmienną środowiskową DOTNET_DiagnosticPorts ustawioną na wartość w danych wyjściowych dotnet-trace .

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

   Powinno to następnie umożliwić dotnet-trace rozpoczęcie śledzenia 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.
   

   Ważne

   Uruchomienie aplikacji dotnet run za pomocą polecenia może być problematyczne, ponieważ interfejs wiersza polecenia dotnet może zduplikować wiele procesów podrzędnych, które nie są Twoją aplikacją, i mogą łączyć się z dotnet-trace nią przed aplikacją, pozostawiając aplikację do zawieszenia w czasie wykonywania. Zaleca się bezpośrednie użycie samodzielnej wersji aplikacji lub użycie dotnet exec jej do uruchamiania aplikacji.

(Tylko system Linux) Zbieranie śladu dla całej maszyny przy użyciu polecenia dotnet-trace

W tym przykładzie są przechwytywane przykłady procesora CPU dla wszystkich procesów na maszynie. Wszystkie procesy z uruchomionym programem .NET 10+ będą również zawierać pewne dodatkowe lekkie zdarzenia opisujące zachowanie ładowania GC, JIT i Zestawu.

$ 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

W przypadku środowisk z wieloma zainstalowanymi wersjami platformy .NET uruchamianie collect-linux w trybie sondowania pomaga określić, czy proces platformy .NET może być śledzony za pomocą funkcji collect-linux.

$ dotnet-trace collect-linux --probe
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

Wyświetlanie śladu przechwyconego z pliku dotnet-trace

W systemie Windows można wyświetlać pliki .nettrace w programie Visual Studio lub PerfView na potrzeby analizy.

W systemie Linux możesz wyświetlić ślad, zmieniając format danych wyjściowych dotnet-trace na speedscope. Zmień format pliku wyjściowego -f|--format przy użyciu opcji . Możesz wybrać między nettrace (opcją domyślną) i speedscope. Opcja -f speedscope spowoduje dotnet-trace utworzenie speedscope pliku. Speedscope pliki można otwierać pod adresem https://www.speedscope.app.

W przypadku śladów zebranych na platformach innych niż Windows można również przenieść plik śledzenia na maszynę z systemem Windows i wyświetlić go w programie Visual Studio lub PerfView.

Uwaga

Środowisko uruchomieniowe platformy .NET Core generuje ślady w nettrace formacie . Ślady są konwertowane na speedscope (jeśli określono) po zakończeniu śledzenia. Ponieważ niektóre konwersje mogą spowodować utratę danych, oryginalny nettrace plik jest zachowywany obok przekonwertowanego pliku.

Użyj pliku rsp, aby uniknąć wpisywania długich poleceń

Możesz uruchomić dotnet-trace plik .rsp zawierający argumenty do przekazania. Może to być przydatne podczas włączania dostawców, którzy oczekują długich argumentów lub w przypadku używania środowiska powłoki, które usuwa znaki.

Na przykład następujący dostawca może być uciążliwy do wpisywania za każdym razem, gdy chcesz śledzić:

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

Ponadto poprzedni przykład zawiera " się jako część argumentu. Ponieważ cudzysłowy nie są obsługiwane w równym stopniu przez każdą powłokę, podczas korzystania z różnych powłok mogą wystąpić różne problemy. Na przykład polecenie, które należy wprowadzić, zsh różni się od polecenia w pliku cmd.

Zamiast wpisywać to za każdym razem, możesz zapisać następujący tekst w pliku o nazwie 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 zapisaniu myprofile.rsppolecenia możesz uruchomić dotnet-trace przy użyciu tej konfiguracji przy użyciu następującego polecenia:

dotnet-trace @myprofile.rsp

Zobacz też

• Dobrze znani dostawcy zdarzeń z platformy .NET