Condividi tramite

Utilità di analisi delle prestazioni dotnet-trace

Questo articolo si applica a: ✔️ dotnet-trace 9.0.661903 e versioni successive

Installare

Esistono due modi per scaricare e installare dotnet-trace:

Riepilogo

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

Descrizione

Lo strumento dotnet-trace:

  • è uno strumento .NET Core multipiattaforma.

  • Abilita la raccolta di analisi .NET Core di un processo in esecuzione senza un profiler nativo.

  • Si basa sul EventPipe del runtime di .NET Core.

  • Supporta due modi diversi per raccogliere tracce:

    • Il collect verbo offre funzionalità coerenti in qualsiasi sistema operativo.
    • Il collect-linux verbo usa funzionalità del sistema operativo specifiche di Linux per fornire funzionalità aggiuntive.
    Caratteristica collect collect-linux
    Sistema operativo supportato Qualunque Solo Linux, versione >kernel = 6.4
    Richiede privilegi di amministratore/radice NO Yes
    Tracciare tutti i processi contemporaneamente NO Sostenuto
    Acquisire la libreria nativa e gli eventi del kernel NO Sostenuto
    Gli stack di chiamate di eventi includono frame nativi NO Yes

Opzioni

  • -h|--help

    Mostra la Guida della riga di comando.

  • --version

    Visualizza la versione dell'utilità dotnet-trace.

Comandi

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

dotnet-trace collect

Raccoglie un’analisi di diagnostica da un processo in esecuzione o avvia un processo figlio e l’analisi (.NET 5 o versione successiva). Per fare in modo che lo strumento esegua un processo figlio e lo tracci dall'avvio, aggiungi -- al comando collect.

Riepilogo

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

Opzioni

  • --buffersize <size>

    Imposta le dimensioni del buffer in memoria, in megabyte. Valore predefinito 256 MB.

    Nota

    Se il processo di destinazione genera eventi più velocemente di quanto possano essere scritti su disco, questo buffer potrebbe essere sovraccaricato e alcuni eventi potrebbero venire eliminati. È possibile risolvere questo problema aumentando le dimensioni del buffer o riducendo il numero di eventi da registrare.

  • --clreventlevel <clreventlevel>

    Dettaglio degli eventi CLR da generare. Questa opzione si applica solo quando --clrevents viene specificato e non sottoposto a override da --profile o --providers. Nella tabella seguente vengono illustrati i livelli di evento disponibili.

    Valore stringa Valore numerico
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Elenco delle parole chiave del provider di runtime CLR da abilitare separate da segni +. Si tratta di un mapping semplice che ti consente di specificare parole chiave evento tramite alias stringa anziché tramite i relativi valori hex. Ad esempio, dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 richiede lo stesso set di eventi di dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Se il provider Microsoft-Windows-DotNETRuntime di runtime CLR è abilitato anche tramite --providers o --profile, questa opzione viene ignorata. La tabella seguente mostra l'elenco delle parole chiave disponibili:

    Alias stringa parola chiave Valore hex parola chiave
    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

    Per altre informazioni sul provider CLR, vedere la documentazione di riferimento del provider di runtime .NET.

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

    Avvia dotnet-dsrouter e si connette a esso. Richiede l'installazione di dotnet-dsrouter . Eseguire dotnet-dsrouter -h per altre informazioni.

  • --format {Chromium|NetTrace|Speedscope}

    Imposta il formato di output per la conversione del file di traccia. Il valore predefinito è NetTrace.

  • -n, --name <name>

    Nome del processo da cui raccogliere la traccia.

    Nota

    In Linux e macOS, l'uso di questa opzione richiede l'applicazione di destinazione e dotnet-trace condividere la stessa TMPDIR variabile di ambiente. In caso contrario, il comando raggiungerà il timeout.

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

    Imposta la porta di diagnostica utilizzata per comunicare con il processo da tracciare. dotnet-trace e il runtime .NET all'interno del processo di destinazione devono accettare l'indirizzo della porta, con un'attesa e l'altra connessione. dotnet-trace determina automaticamente la porta corretta durante il collegamento usando le --process-id opzioni o --name o quando si avvia un processo usando l'opzione -- <command> . In genere è necessario specificare la porta in modo esplicito quando si attende un processo che verrà avviato in futuro o comunicando a un processo in esecuzione all'interno di un contenitore che non fa parte dello spazio dei nomi del processo corrente.

    Il valore port-address è diverso dal sistema operativo:

    • Linux e macOS: percorso di un socket di dominio Unix, /foo/tool1.socketad esempio .
    • Windows: percorso di una named pipe, \\.\pipe\my_diag_port1ad esempio .
    • Android, iOS e tvOS: una porta IP, ad esempio 127.0.0.1:9000.

    Per impostazione predefinita, dotnet-trace rimane in ascolto dell'indirizzo specificato. È possibile richiedere dotnet-trace invece di connettersi aggiungendo ,connect dopo l'indirizzo. Ad esempio, --diagnostic-port /foo/tool1.socket,connect si connetterà a un processo di runtime .NET in ascolto del socket di /foo/tool1.socket dominio Unix.

    Per informazioni su come usare questa opzione per raccogliere una traccia dall'avvio dell'app, vedere Usare la porta di diagnostica per raccogliere una traccia dall'avvio dell'app.

  • --duration <time-to-run>

    Ora di esecuzione della traccia. Usa il formato dd:hh:mm:ss. Ad esempio 00:00:00:05 la eseguirà per 5 secondi.

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

    Percorso di output per i dati di traccia raccolti. Se non è specificato, per impostazione predefinita <appname>_<yyyyMMdd>_<HHmmss>.nettraceè , ad esempio ,'myapp_20210315_111514.nettrace'.

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

    ID processo da cui raccogliere la traccia.

    Nota

    In Linux e macOS, l'uso di questa opzione richiede l'applicazione di destinazione e dotnet-trace condividere la stessa TMPDIR variabile di ambiente. In caso contrario, il comando raggiungerà il timeout.

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

    Un profilo è un set predefinito di configurazioni del provider per scenari di traccia comuni. È possibile specificare più profili alla volta, delimitati da virgole. I provider configurati tramite --providers l'override della configurazione del profilo. Analogamente, se un profilo configura il provider di runtime CLR, eseguirà l'override di tutte le configurazioni previste tramite --clrevents.

    Quando --profile, --providerse --clrevents vengono tutti omessi, dotnet-trace collect abilita i profili dotnet-common e dotnet-sampled-thread-time per impostazione predefinita.

    Profili disponibili:

    Profilo Descrizione
    dotnet-common Diagnostica leggera del runtime .NET progettata per rimanere a basso sovraccarico.
    Include eventi GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap e Compilation
    Equivalente a --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Esempi di stack di thread .NET (~100 Hz) per identificare gli hotspot nel tempo. Usa il profiler di esempio di runtime con stack gestiti.
    gc-verbose Tiene traccia delle raccolte GC e delle allocazioni di oggetti di esempio.
    gc-collect Tiene traccia delle raccolte GC solo a un sovraccarico molto basso.
    database Acquisisce ADO.NET e i comandi del database Entity Framework.

    Nota

    Nelle versioni precedenti dello strumento dotnet-trace il verbo collect supporta un profilo denominato cpu-sampling. Questo profilo è stato rimosso perché il nome è fuorviante. Ha campionato tutti i thread indipendentemente dall'utilizzo della CPU. È ora possibile ottenere un risultato simile usando --profile dotnet-sampled-thread-time,dotnet-common. Se è necessario trovare esattamente la corrispondenza con il comportamento precedente cpu-sampling , usare --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

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

    Elenco delimitato da virgole di provider EventPipe da abilitare. Questi provider integrano tutti i provider impliciti in --profile <list-of-comma-separated-profile-names>. Se esiste una incoerenza per un provider specifico, questa configurazione ha la precedenza sulla configurazione implicita da --profile e --clrevents.

    Questo elenco di provider è nel formato Provider[,Provider]:

    • Provider è nel formato: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs è nel formato: [key1=value1][;key2=value2]

    Per altre informazioni su alcuni dei provider noti in .NET, vedere Provider di eventi noti.

  • -- <command> (per le applicazioni di destinazione che eseguono .NET 5 o versioni successive)

    Dopo i parametri di configurazione della raccolta, l'utente può accodare -- seguito da un comando per avviare un'applicazione .NET con almeno un runtime 5.0. Ciò può risultare utile durante la diagnosi dei problemi che si verificano all'inizio del processo, ad esempio problemi di prestazioni all’avvio o relativi al caricatore di assembly ed errori binder.

    Nota

    L'uso di questa opzione monitora il primo processo .NET che comunica di nuovo allo strumento, ovvero se il comando avvia più applicazioni .NET, raccoglierà solo la prima app. Pertanto, è consigliabile usare questa opzione nelle applicazioni autonome o usando l'opzione dotnet exec <app.dll>.

  • --show-child-io

    Mostra i flussi di input e output di un processo figlio avviato nella console corrente.

  • --resume-runtime

    Riprendere il runtime dopo l'inizializzazione della sessione, il valore predefinito è true. Disabilitare la ripresa del runtime usando --resume-runtime:false.

  • --stopping-event-provider-name

    Stringa, analizzata così come è, che interromperà l’analisi al raggiungimento di un evento con il nome del provider corrispondente. Per un evento di arresto più specifico, specificare anche --stopping-event-event-name e/o --stopping-event-payload-filter. Ad esempio, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime per arrestare la traccia quando raggiunge il primo evento generato dal Microsoft-Windows-DotNETRuntime provider di eventi.

  • --stopping-event-event-name

    Stringa, analizzata così come è, che interromperà l’analisi al raggiungimento di un evento con il nome dell’evento corrispondente. --stopping-event-provider-name deve essere impostato. Per un evento di arresto più specifico, specificare anche --stopping-event-payload-filter. Ad esempio, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted per arrestare la traccia quando raggiunge il primo Method/JittingStarted evento generato dal Microsoft-Windows-DotNETRuntime provider di eventi.

  • --stopping-event-payload-filter

    Stringa, analizzata come coppie [payload_field_name]:[payload_field_value] separate da virgole, che interromperà l’analisi al raggiungimento di un evento contenente tutte le coppie di payload specificate. --stopping-event-provider-name e --stopping-event-event-name devono essere impostati. Ad esempio, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick per arrestare la traccia al primo Method/JittingStarted evento per il metodo OnButtonClick nello Program spazio dei nomi generato dal Microsoft-Windows-DotNETRuntime provider di eventi.

Nota

  • L'arresto dell’analisi può richiedere molto tempo (fino ad alcuni minuti) per le applicazioni di grandi dimensioni. Il runtime deve inviare la cache dei tipi per tutto il codice gestito acquisito nell’analisi.
  • Per raccogliere un’analisi utilizzando dotnet-trace, è necessario che venga eseguito come stesso utente che esegue il processo target o come radice. In caso contrario, lo strumento non riuscirà a stabilire una connessione con il processo di destinazione.
  • Se si verifica un'eccezione non gestita durante l'esecuzione di dotnet-trace collect, viene generata un’analisi incompleta. Se la tua priorità è trovare la causa radice dell'eccezione, accedi a Raccogli dump in caso di arresto anomalo. In seguito all'eccezione non gestita, l’analisi viene troncata quando il runtime viene arrestato per evitare altri comportamenti indesiderati, come un blocco o un danneggiamento dei dati. Anche se l’analisi è incompleta, puoi comunque aprirla per vedere cos’ha causato l’errore. Tuttavia, mancheranno le informazioni di rundown (questo avviene alla fine di un’analisi) e gli stack potrebbero non essere risolti (a seconda dei provider attivati). Apri l’analisi eseguendo PerfView con il flag /ContinueOnError nella riga di comando. I log conterranno anche il percorso in cui è stata generata l'eccezione.
  • Quando si specifica un evento di arresto tramite le opzioni --stopping-event-*, poiché EventStream viene analizzato in modo asincrono, ci saranno alcuni eventi che passano tra il momento in cui viene analizzato un evento di traccia corrispondente alle opzioni di evento di arresto specificate e l’arresto di EventPipeSession.

dotnet-trace collect-linux

Nota

Il collect-linux verbo è una nuova funzionalità di anteprima e si basa su una versione aggiornata del formato di file .nettrace. La versione più recente di PerfView supporta questi file di traccia, ma altri modi per usare il file di traccia, ad esempio convert e report, potrebbero non funzionare ancora.

Raccoglie tracce di diagnostica usando perf_events, una tecnologia del sistema operativo Linux. collect-linux abilita le funzionalità aggiuntive seguenti su collect.

raccogliere collect-linux
Sistema operativo supportato Qualunque Solo Linux, versione >kernel = 6.4
Richiede privilegi di amministratore/radice NO Yes
Tracciare tutti i processi contemporaneamente NO Sostenuto
Acquisire la libreria nativa e gli eventi del kernel NO Sostenuto
Gli stack di chiamate di eventi includono frame nativi NO Yes

Prerequisiti

  • Kernel Linux con CONFIG_USER_EVENTS=y supporto (kernel 6.4+)
  • Autorizzazioni radice
  • .NET 10+

Nota

Il collect-linux verbo viene eseguito solo in ambienti linux x64 e linux arm64 con glibc versione 2.35 o successiva. Tutte le distribuzioni di Linux supportate ufficialmente da .NET 10 supportano questo requisito, ad eccezione di Alpine 3.22, CentOS Stream 9 ed eventuali distribuzioni basate su Red Hat Enterprise Linux 9. Un modo rapido per controllare la versione di libc di un sistema è con il comando ldd --version o eseguendo direttamente la libreria libc.

Riepilogo

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]

Comportamento predefinito della raccolta

Quando --providers, --profile, --clreventse --perf-events non vengono specificati, collect-linux abilita questi profili per impostazione predefinita:

  • dotnet-common — diagnostica leggera del runtime .NET.
  • cpu-sampling — campionamento della CPU del kernel.

Per impostazione predefinita, tutti i processi nel computer vengono tracciati. Per tracciare un solo processo, usare -n, --name <name> o -p|--process-id <PID>.

Opzioni

Opzioni di specifica provider/evento

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

    Elenco delimitato da virgole di provider EventPipe da abilitare. Questi provider integrano tutti i provider impliciti in --profile <list-of-comma-separated-profile-names>. Se esiste una incoerenza per un provider specifico, questa configurazione ha la precedenza sulla configurazione implicita da --profile e --clrevents.

    Questo elenco di provider è nel formato Provider[,Provider]:

    • Provider è nel formato: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs è nel formato: [key1=value1][;key2=value2]

    Per altre informazioni su alcuni dei provider noti in .NET, vedere Provider di eventi noti.

  • --clreventlevel <clreventlevel>

    Dettaglio degli eventi CLR da generare. Questa opzione si applica solo quando --clrevents viene specificato e non sottoposto a override da --profile o --providers. Nella tabella seguente vengono illustrati i livelli di evento disponibili.

    Valore stringa Valore numerico
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Elenco delle parole chiave del provider di runtime CLR da abilitare separate da segni +. Si tratta di un mapping semplice che ti consente di specificare parole chiave evento tramite alias stringa anziché tramite i relativi valori hex. Ad esempio, dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 richiede lo stesso set di eventi di dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Se il provider Microsoft-Windows-DotNETRuntime di runtime CLR è abilitato anche tramite --providers o --profile, questa opzione viene ignorata. La tabella seguente mostra l'elenco delle parole chiave disponibili:

    Alias stringa parola chiave Valore hex parola chiave
    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

    Per altre informazioni sul provider CLR, vedere la documentazione di riferimento del provider di runtime .NET.

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

    Elenco delimitato da virgole di eventi di prestazioni da includere nella traccia. Gli eventi disponibili sono disponibili in tracefs, che in genere è montato in /sys/kernel/tracing, attraverso available_events per tutti gli eventi disponibili o tramite la events/ sottodirectory per gli eventi classificati.

    Esempio: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

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

    Un profilo è un set predefinito di configurazioni del provider per scenari di traccia comuni. È possibile specificare più profili alla volta, delimitati da virgole. I provider configurati tramite --providers l'override della configurazione del profilo. Analogamente, se un profilo configura il provider di runtime CLR, eseguirà l'override di tutte le configurazioni previste tramite --clrevents.

    Quando --profile, --providers, --clreventse --perf-events vengono tutti omessi, dotnet-trace collect-linux abilita i profili dotnet-common e cpu-sampling per impostazione predefinita.

    Profili disponibili:

    Profilo Descrizione
    dotnet-common Diagnostica leggera del runtime .NET progettata per rimanere a basso sovraccarico.
    Include eventi GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap e Compilation
    Equivalente a --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    cpu-sampling Campionamento della CPU del kernel (basato su prestazioni), generato come Universal.Events/cpu, per un'attribuzione precisa della CPU.
    thread-time Commutatori del contesto del thread kernel, generati come , per l'analisi della CPU e dell'utilità di pianificazione on/off.Kernel context switch, emitted as Universal.Events/cswitch, for on/off-CPU and scheduler analysis.
    gc-verbose Tiene traccia delle raccolte GC e delle allocazioni di oggetti di esempio.
    gc-collect Tiene traccia delle raccolte GC solo a un sovraccarico molto basso.
    database Acquisisce ADO.NET e i comandi del database Entity Framework.

Opzioni della raccolta di tracce

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

    Percorso di output per i dati di traccia raccolti. Se non specificato, per impostazione predefinita viene predefinito trace_<yyyyMMdd>_<HHmmss>.nettrace per la traccia a livello di computer e <appname>_<yyyyMMdd>_<HHmmss>.nettrace per una traccia specifica del processo (--name o --process-id)

  • --duration <time-to-run>

    Ora di esecuzione della traccia. Usa il formato dd:hh:mm:ss. Ad esempio 00:00:00:05 la eseguirà per 5 secondi.

Opzioni di destinazione del processo .NET

Vedere Comportamento predefinito della raccolta

  • -n, --name <name>

    Nome del processo da cui raccogliere la traccia.

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

    ID processo da cui raccogliere la traccia.

Opzioni della modalità probe

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

    Eseguire il probe dei processi .NET per il supporto del comando IPC EventPipe UserEvents usato da collect-linux, senza raccogliere una traccia. Per prima cosa, l'elenco dei risultati supporta i processi supportati. Usare '-o stdout' per stampare csv (pid,processName,supportsCollectLinux) nella console o '-o output-filename' per scrivere il file CSV. Eseguire il probe di un singolo processo con -n|--name o -p|--process-id.

    Poiché l'esecuzione collect-linux in modalità probe non raccoglie una traccia, non richiede autorizzazioni radice per l'esecuzione. Non fornisce la convalida dei prerequisiti e i processi .NET in esecuzione nelle versioni di anteprima di .NET Runtime '10.0.0' sono considerati non supportati.

Nota

Per raccogliere una traccia usando dotnet-trace collect-linux, deve essere eseguita con le autorizzazioni radice (/CAP_PERFMONCAP_SYS_ADMIN). In caso contrario, lo strumento non riuscirà a raccogliere eventi.

dotnet-trace convert

Converte le analisi nettrace in formati alternativi, da utilizzare con strumenti di analisi di traccia alternativi.

Riepilogo

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

Argomenti

  • <input-filename>

    File di traccia di input da convertire. L'impostazione predefinita è trace.nettrace.

Opzioni

  • --format <Chromium|NetTrace|Speedscope>

    Imposta il formato di output per la conversione del file di traccia.

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

    Nome file di output. Verrà aggiunta l'estensione del formato di destinazione.

Nota

La conversione di file nettrace in file chromium o speedscope è irreversibile. I file speedscope e chromium non hanno tutte le informazioni necessarie per ricostruire i file nettrace. Tuttavia, il comando convert mantiene il file nettrace originale, quindi non eliminare questo file se prevedi di aprirlo in futuro.

dotnet-trace ps

Elenca i processi dotnet da cui è possibile raccogliere le tracce. dotnet-trace 6.0.320703 e versioni successive mostrano anche gli argomenti della riga di comando con cui è stato avviato ogni processo, se disponibile.

Nota

Per ottenere informazioni complete per i processi a 64 bit enumerati, è necessario usare una versione a 64 bit dello dotnet-trace strumento.

Riepilogo

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

Esempio

Si supponga di avviare un'app a esecuzione prolungata usando il comando dotnet run --configuration Release. In un'altra finestra si esegue il comando dotnet-trace ps. L'output visualizzato è il seguente. Gli argomenti della riga di comando, se disponibili, vengono visualizzati nella versione dotnet-trace 6.0.320703 e successive.

> 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

Elenca i profili di analisi predefiniti con una descrizione dei provider e dei filtri presenti in ogni profilo.

Riepilogo

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

dotnet-trace report

Crea un report in stdout da una traccia generata in precedenza.

Riepilogo

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

Argomenti

  • <tracefile>

    Percorso del file della traccia analizzata.

Comandi

dotnet-trace report topN

Trova i primi N metodi che sono stati nello stack di chiamate più lungo.

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

Fornisce i primi N metodi nello stack di chiamate.

  • --inclusive

Restituisce i primi N metodi in base al tempo inclusivo. Se non specificato, il tempo esclusivo viene utilizzato per impostazione predefinita.

  • -v|--verbose

Restituisci i parametri di ogni metodo in modo completo. Se non specificato, i parametri verranno troncati.

Raccogli una traccia con dotnet-trace

Per raccogliere tracce usando dotnet-trace collect:

  • Ottieni l'identificatore del processo (PID) dell'applicazione .NET Core da cui raccogliere le tracce.

    • Ad esempio, in Windows è possibile usare Gestione attività o il comando tasklist.
    • In Linux, ad esempio, il comando ps.
    • dotnet-trace ps

  • Esegui questo comando:

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

    Il comando precedente genera un output simile al seguente:

    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.

  • Arrestare la raccolta premendo INVIO . dotnet-trace terminerà la registrazione degli eventi nel .nettrace file.

Avvia un'applicazione figlio e raccogli una traccia dall'avvio usando dotnet-trace

A volte può essere utile raccogliere una traccia di un processo dall'avvio. Per le app che eseguono .NET 5 o versioni successive, è possibile eseguire questa operazione usando dotnet-trace.

Verrà avviato hello.exe con arg1 e arg2 come argomenti della riga di comando e verrà raccolta una traccia dall'avvio del runtime:

dotnet-trace collect -- hello.exe arg1 arg2

Il comando precedente genera un output simile al seguente:

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

Puoi interrompere la raccolta della traccia premendo i tasto <Enter> o <Ctrl + C>. In questo modo si uscirà anche da hello.exe.

Nota

L'avvio di hello.exe tramite dotnet-trace reindirizzerà l'input/output e per impostazione predefinita non sarà possibile interagire con esso nella console. Usa l'opzione --show-child-io per interagire con stdin/stdout. L'uscita dallo strumento tramite CTRL+C o SIGTERM terminerà in modo sicuro sia lo strumento che il processo figlio. Se il processo figlio viene chiuso prima dello strumento, lo strumento verrà chiuso e la traccia dovrebbe essere visualizzabile in modo sicuro.

Usa la porta di diagnostica per raccogliere una traccia dall'avvio dell'app

La porta di diagnostica è una funzionalità di runtime aggiunta in .NET 5 che ti consente di avviare il tracciamento dall'avvio dell'app. A tale scopo, usando dotnet-trace, è possibile usare dotnet-trace collect -- <command> come descritto negli esempi precedenti oppure usare l'opzione --diagnostic-port.

L'uso di dotnet-trace <collect|monitor> -- <command> per avviare l'applicazione come processo figlio è il modo più semplice per tracciare rapidamente l'applicazione dall'avvio.

Tuttavia, quando si vuole ottenere un controllo più preciso sulla durata dell'app tracciata (ad esempio, monitorare l'app solo per i primi 10 minuti e continuare l'esecuzione) o se è necessario interagire con l'app usando l'interfaccia della riga di comando, l'opzione --diagnostic-port ti consente di controllare sia l'app di destinazione monitorata che dotnet-trace.

  1. Il comando seguente fa sì che dotnet-trace crei un socket di diagnostica denominato myport.sock e attenda una connessione.

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

    Risultato:

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

  2. In una console separata, avvia l'applicazione di destinazione con la variabile di ambiente DOTNET_DiagnosticPorts impostata sul valore nell'output dotnet-trace.

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

    Verrà quindi abilitato dotnet-trace per avviare il tracciamento 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.

    Importante

    L'avvio dell'app con dotnet run può essere problematico perché l'interfaccia della riga di comando dotnet può generare molti processi figlio che non sono l'app e possono connettersi prima dotnet-trace dell'app, lasciando l'app sospesa in fase di esecuzione. È consigliabile usare direttamente una versione autonoma dell'app o usare dotnet exec per avviare l'applicazione.

(solo Linux) Raccogliere una traccia a livello di computer usando dotnet-trace

In questo esempio vengono acquisiti esempi di CPU per tutti i processi nel computer. Tutti i processi che eseguono .NET 10+ includono anche alcuni eventi leggeri aggiuntivi che descrivono il comportamento di caricamento GC, JIT e Assembly.

$ 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

Per gli ambienti con più versioni .NET installate, l'esecuzione collect-linux in modalità probe consente di distinguere se un processo .NET è in grado di essere tracciato con 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'

Visualizzare la traccia acquisita da dotnet-trace

In Windows puoi visualizzare i file .nettrace in Visual Studio o PerfView per l'analisi.

In Linux puoi visualizzare la traccia modificando il formato di output di dotnet-trace in speedscope. Modifica il formato del file di output tramite l'opzione -f|--format. Puoi scegliere tra nettrace (opzione predefinita) e speedscope. L'opzione -f speedscope farà sì che dotnet-trace produca un file speedscope. I file Speedscope possono essere aperti in https://www.speedscope.app.

Per le tracce raccolte su piattaforme non Windows, puoi anche spostare il file di traccia in un computer Windows e visualizzarlo in Visual Studio o PerfView.

Nota

Il runtime .NET Core genera tracce nel formato nettrace. Le tracce vengono convertite in ambito rapido (se specificato) dopo il completamento della traccia. Poiché alcune conversioni possono comportare la perdita di dati, il file originale nettrace viene conservato accanto al file convertito.

Usa il file .rsp per evitare di digitare comandi lunghi

È possibile avviare dotnet-trace con un file .rsp che contiene gli argomenti da passare. Ciò può essere utile quando si abilitano provider che prevedono argomenti lunghi o quando si usa un ambiente della shell che rimuove i caratteri.

Ad esempio, il provider seguente può essere complesso da digitare ogni volta che intendi tracciare:

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

Inoltre, l'esempio precedente contiene " come parte dell'argomento. Poiché le virgolette non vengono gestite allo stesso modo da ogni shell, è possibile che si verifichino vari problemi quando si usano shell diverse. Ad esempio, il comando da immettere in zsh è diverso dal comando in cmd.

Anziché digitarlo ogni volta, puoi salvare il testo seguente in un file denominato 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

Dopo aver salvato myprofile.rsp, puoi avviare dotnet-trace con questa configurazione usando il comando seguente:

dotnet-trace @myprofile.rsp

Vedi anche

  • Last updated on