Compartir a través de

Utilidad de análisis de rendimiento dotnet-trace

  • Artículo

Este artículo se aplica a: ✔️ dotnet-trace 3.0.47001 y versiones posteriores

Instalar

Hay dos maneras de descargar e instalar dotnet-trace:

  • Herramienta global dotnet:

    Para instalar la versión de lanzamiento más reciente del paquete NuGet de dotnet-trace, use el comando dotnet tool install:

    dotnet tool install --global dotnet-trace

  • Descarga directa:

    descargue el archivo ejecutable de la herramienta que coincida con la plataforma:

    SO Plataforma
    Windows x86 | x64 | Arm | Arm-x64
    Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Sinopsis

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

Descripción

La herramienta dotnet-trace:

  • Es una herramienta de .NET Core para varias plataformas.
  • Habilita la recolección de seguimientos de .NET Core de un proceso en ejecución sin un generador de perfiles nativo.
  • Se basa en EventPipe del entorno de ejecución de .NET Core.
  • Ofrece la misma experiencia en Windows, Linux o macOS.

Opciones

  • -h|--help

    Muestra la ayuda de la línea de comandos.

  • --version

    Muestra la versión de la utilidad dotnet-trace.

  • --duration

    Cuánto tiempo ejecutar el seguimiento. --duration 00:00:00:05 lo ejecutará durante 5 segundos.

Comandos:

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

dotnet-trace collect

Recopila un seguimiento de diagnóstico desde un proceso en ejecución o inicia un proceso secundario y realiza su seguimiento (en .NET 5 o posterior). Para que la herramienta ejecute un proceso secundario y realice su seguimiento desde su inicio, anexe -- al comando de recopilación.

Sinopsis

dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--clrevents <clrevents>]
    [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [--duration dd:hh:mm:ss]
    [-n, --name <name>] [--diagnostic-port] [-o|--output <trace-file-path>] [-p|--process-id <pid>]
    [--profile <profile-name>] [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io] [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

Opciones

  • --buffersize <size>

    Establece el tamaño del búfer en memoria, en megabytes. Valor predeterminado de 256 MB.

    Nota:

    Si el proceso de destino emite eventos más rápido de lo que se pueden escribir en el disco, este búfer puede desbordarse y algunos eventos se anularán. Puede mitigar este problema aumentando el tamaño de búfer o reduciendo el número de eventos que se registran.

  • --clreventlevel <clreventlevel>

    Nivel de detalle de los eventos CLR que se van a emitir. En la tabla siguiente se muestran los niveles de eventos disponibles.

    Valor de cadena Valor numérico
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Lista de palabras clave del proveedor del entorno de ejecución de CLR para habilitación separadas por signos +. Se trata de una asignación simple que le permite especificar palabras clave de eventos mediante alias de cadenas en lugar de sus valores hexadecimales. Por ejemplo, dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 solicita el mismo conjunto de eventos que dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. En la tabla siguiente, se muestra la lista de palabras clave disponibles:

    Alias de cadena de palabra clave Valor hexadecimal de palabra clave
    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

    Puede obtener información más detallada sobre el proveedor de CLR en la documentación de referencia del proveedor del entorno de ejecución de .NET.

  • --format {Chromium|NetTrace|Speedscope}

    Establece el formato de salida para la conversión del archivo de seguimiento. De manera predeterminada, es NetTrace.

  • -n, --name <name>

    Nombre del proceso del que se va a recopilar el seguimiento.

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

    Nombre del puerto de diagnóstico que se va a crear. Vea Uso del puerto de diagnóstico para recopilar un seguimiento desde el inicio de la aplicación para obtener información sobre cómo usar esta opción para recopilar un seguimiento desde el inicio de la aplicación.

  • --duration <time-to-run>

    El tiempo para que se ejecute el seguimiento. Use el formato dd:hh:mm:ss. Por ejemplo, 00:00:00:05 lo ejecutará durante 5 segundos.

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

    Ruta de acceso de salida para los datos de seguimiento recopilados. Si no se especifica, el valor predeterminado es <appname>_<yyyyMMdd>_<HHmmss>.nettrace, por ejemplo, "myapp_20210315_111514.nettrace".

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

    Identificador del proceso del que se va a recopilar el seguimiento.

  • --profile <profile-name>

    Un conjunto con nombre predefinido de configuraciones de proveedor que permite especificar sucintamente los escenarios de seguimiento comunes. Hay disponibles los perfiles siguientes:

Perfil Descripción
cpu-sampling Resulta útil para realizar el seguimiento del uso de CPU y la información general del entorno de ejecución de .NET. Esta es la opción predeterminada si no se especifica ningún perfil o proveedor.
gc-verbose Realiza un seguimiento de las recolecciones de elementos no utilizados y las asignaciones de objetos de ejemplo.
gc-collect Realiza un seguimiento de las recolecciones de elementos no utilizados solo con una sobrecarga muy baja.

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

    Lista separada por comas de proveedores de EventPipe que se van a habilitar. Estos proveedores complementan a los proveedores implícitos en --profile <profile-name>. Si hay alguna incoherencia para un proveedor determinado, esta configuración tiene prioridad sobre la configuración implícita del perfil.

    Esta lista de proveedores tiene el siguiente formato:

    • Provider[,Provider]
    • Provider tiene el formato: KnownProviderName[:Flags[:Level][:KeyValueArgs]].
    • KeyValueArgs tiene el formato: [key1=value1][;key2=value2].

    Para obtener más información acerca de algunos de los proveedores conocidos en .NET, consulte Proveedores de eventos conocidos en .NET.

  • -- <command> (para aplicaciones de destino que ejecutan .NET 5 o posterior)

    Después de los parámetros de configuración de la colección, el usuario puede anexar -- seguido de un comando para iniciar una aplicación de .NET con un entorno de ejecución de 5.0 como mínimo. Esto puede resultar útil al diagnosticar problemas que se producen al principio del proceso, como problemas de rendimiento de inicio o de cargador de ensamblados y errores del enlazador.

    Nota:

    Con esta opción se supervisa el primer proceso de .NET que se comunica de nuevo con la herramienta, lo que significa que si el comando inicia varias aplicaciones .NET, solo recopilará la primera aplicación. Por tanto, se recomienda usar esta opción en aplicaciones independientes, o bien utilizar la opción dotnet exec <app.dll>.

  • --show-child-io

    Muestra los flujos de entrada y salida de un proceso secundario iniciado en la consola actual.

  • --resume-runtime

    Reanude el tiempo de ejecución una vez inicializada la sesión, el valor predeterminado es true. Deshabilite el reanudación del tiempo de ejecución mediante --resume-runtime:false.

  • --stopping-event-provider-name

    Cadena, analizada tal y como está, que detendrá el seguimiento al alcanzar un evento con el nombre del proveedor coincidente. Para un evento de detención más específico, proporcione además --stopping-event-event-name o --stopping-event-payload-filter. Por ejemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime para detener el seguimiento al alcanzar el primer evento emitido por el proveedor de eventos Microsoft-Windows-DotNETRuntime.

  • --stopping-event-event-name

    Cadena, analizada tal y como está, que detendrá el seguimiento al alcanzar un evento con el nombre del evento coincidente. Requiere establecer --stopping-event-provider-name. Para un evento de detención más específico, proporcione además --stopping-event-payload-filter. Por ejemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted a detener el seguimiento al alcanzar el primer evento de Method/JittingStarted emitido por el proveedor de eventos Microsoft-Windows-DotNETRuntime.

  • --stopping-event-payload-filter

    Cadena, analizada como [payload_field_name]:[payload_field_value] pares separados por comas, que detendrán el seguimiento al alcanzar un evento que contiene todos los pares de carga especificados. Requiere establecer --stopping-event-provider-name y --stopping-event-event-name. Por ejemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick a detener el seguimiento en el primer evento de Method/JittingStarted para el método OnButtonClick en el espacio de nombres Program emitido por el proveedor de eventos Microsoft-Windows-DotNETRuntime.

Nota:

  • En aplicaciones de gran tamaño, detener el seguimiento puede tardar mucho tiempo (hasta minutos). El entorno de ejecución debe enviar a través de la memoria caché de tipos todo el código administrado que se capturó en el seguimiento.
  • En Linux y macOS, este comando espera que la aplicación de destino y dotnet-trace compartan la misma variable de entorno TMPDIR. De lo contrario, se agotará el tiempo de espera del comando.
  • Para recopilar un seguimiento mediante dotnet-trace, debe ejecutarse como el mismo usuario que el que ejecuta el proceso de destino, o bien como usuario raíz. De lo contrario, la herramienta no podrá establecer una conexión con el proceso de destino.
  • Si experimenta una excepción no controlada al ejecutar dotnet-trace collect, se produce un seguimiento incompleto. Si encontrar la causa principal de la excepción es su prioridad, vaya a Recopilar volcados de memoria en el bloqueo. Como resultado de la excepción no controlada, el seguimiento se trunca cuando el tiempo de ejecución se cierra para evitar otro comportamiento no deseado, como un bloqueo o daños en los datos. Aunque el seguimiento sea incompleto, todavía puede abrirlo para ver lo que ha ocurrido antes del error. Sin embargo, faltará información de Rundown (esto sucede al final de un seguimiento), por lo que es posible que las pilas no se resuelvan (dependiendo de los proveedores que estuvieran activados). Abra el seguimiento ejecutando PerfView con la marca /ContinueOnError en la línea de comandos. Los registros también contendrán la ubicación en la que se desencadenó la excepción.
  • Al especificar un evento de detención a través de las opciones de --stopping-event-*, a medida que EventStream se analiza de forma asincrónica, habrá algunos eventos que pasan entre el momento en que se analiza un evento de seguimiento que coincide con las opciones de evento de detención especificadas y se detiene EventPipeSession.

dotnet-trace convert

Convierte los seguimientos de nettrace en formatos alternativos para usarlos con herramientas de análisis de seguimiento alternativas.

Sinopsis

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

Argumentos

  • <input-filename>

    Archivo de seguimiento de entrada que se va a convertir. El valor predeterminado es trace.nettrace.

Opciones

  • --format <Chromium|NetTrace|Speedscope>

    Establece el formato de salida para la conversión del archivo de seguimiento.

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

    Nombre de archivo de salida. Se agregará la extensión del formato de destino.

Nota

La conversión de archivos nettrace en archivos chromium o speedscope es irreversible. Los archivos speedscope y chromium no tienen toda la información necesaria para reconstruir los archivos nettrace, pero el comando convert conserva el archivo nettrace original, por lo que no debe eliminar este archivo si tiene previsto abrirlo en el futuro.

dotnet-trace ps

Enumera los procesos de dotnet de los que se pueden recopilar seguimientos. dotnet-trace 6.0.320703 y posteriores también muestran los argumentos de la línea de comandos con los que se ha iniciado cada proceso, si están disponibles.

Nota:

Para obtener información completa para los procesos de 64 bits enumerados, debe usar una versión de 64 bits de la dotnet-trace herramienta.

Sinopsis

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

Ejemplo

Imagine que inicia una aplicación de ejecución prolongada con el comando dotnet run --configuration Release. En otra ventana ejecuta el comando dotnet-trace ps. La salida que se ve es la siguiente. Los argumentos de la línea de comandos, si los hay, se muestran en dotnet-trace versión 6.0.320703 y posteriores.

> 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

Muestra los perfiles de seguimiento pregenerados con una descripción de los proveedores y filtros que hay en cada perfil.

Sinopsis

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

dotnet-trace report

Crea un informe en stdout a partir de un seguimiento generado previamente.

Sinopsis

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

Argumentos

  • <tracefile>

    Ruta de acceso del archivo para el seguimiento que se analiza.

Comandos

dotnet-trace report topN

Busca los principales métodos N que más tiempo han estado en la pila de llamadas.

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

Proporciona los principales métodos N en la pila de llamadas.

  • --inclusive

Genere los principales métodos N en función del tiempo inclusivo. Si no se especifica, se usa el tiempo exclusivo de forma predeterminada.

  • -v|--verbose

Genere los parámetros de cada método en su totalidad. Si no se especifica, se truncarán los parámetros.

Recopilación de un seguimiento con dotnet-trace

Para recopilar seguimientos mediante dotnet-trace:

  • Averigüe el identificador de proceso (PID) de la aplicación .NET Core del que se van a recopilar seguimientos.

    • En Windows, puede usar el administrador de tareas o el comando tasklist, por ejemplo.
    • En Linux, por ejemplo, el comando ps.
    • dotnet-trace ps

  • Ejecute el siguiente comando:

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

    El comando anterior genera una salida similar a la siguiente:

    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)

  • Detenga la recolección presionando la tecla <Enter>. dotnet-trace finalizará el registro de eventos en el archivo trace.nettrace.

Inicio de una aplicación secundaria y recopilación de un seguimiento de su inicio mediante dotnet-trace

A veces puede resultar útil recopilar un seguimiento de un proceso desde su inicio. En el caso de las aplicaciones que ejecutan .NET 5 o versiones posteriores, es posible hacerlo mediante dotnet-trace.

Esto iniciará hello.exe con arg1 y arg2 como argumentos de la línea de comandos y recopilará un seguimiento de su inicio en tiempo de ejecución:

dotnet-trace collect -- hello.exe arg1 arg2

El comando anterior genera una salida similar a la siguiente:

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

Para detener la recopilación del seguimiento, presione <Enter> o las teclas <Ctrl + C>. Si lo hace, también saldrá de hello.exe.

Nota

El inicio de hello.exe mediante dotnet-trace redirigirá su entrada/salida y no podrá interactuar con el archivo en la consola de forma predeterminada. Use el modificador --show-child-io para interactuar con su stdin/stdout. La salida de la herramienta por medio de Ctrl + C o SIGTERM finalizará con seguridad la herramienta y el proceso secundario. Si el proceso secundario termina antes que la herramienta, la herramienta también se cerrará y el seguimiento se debe poder ver de forma segura.

Uso del puerto de diagnóstico para recopilar un seguimiento desde el inicio de la aplicación

El puerto de diagnóstico es una característica del runtime añadida en .NET 5, que permite realizar un seguimiento desde el inicio de la aplicación. Para hacer esto con dotnet-trace, puede usar dotnet-trace collect -- <command>, tal como se describe en los ejemplos anteriores, o bien la opción --diagnostic-port.

El uso de dotnet-trace <collect|monitor> -- <command> para iniciar la aplicación como un proceso secundario es la manera más sencilla de realizar el seguimiento rápido de la aplicación desde el inicio.

Sin embargo, si quiere obtener un control más preciso sobre la vigencia de la aplicación de la que se realiza el seguimiento (por ejemplo, supervisar la aplicación solo durante los primeros 10 minutos y continuar la ejecución), o si necesita interactuar con la aplicación mediante la CLI, el uso de la opción --diagnostic-port le permite controlar la aplicación de destino que se supervisa y dotnet-trace.

  1. El comando siguiente hace que dotnet-trace cree un socket de diagnóstico denominado myport.sock y que espere a una conexión.

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

    Salida:

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

  2. En una consola independiente, inicie la aplicación de destino con la variable de entorno DOTNET_DiagnosticPorts establecida en el valor de la salida de dotnet-trace.

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

    Esto debe habilitar dotnet-trace para iniciar el seguimiento de 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

    Iniciar la aplicación con dotnet run puede resultar problemático porque la CLI de dotnet puede generar muchos procesos secundarios que no sean de la aplicación. Además, dichos procesos pueden conectarse a dotnet-trace antes que la aplicación, lo que causa que esta se suspenda en tiempo de ejecución. Se recomienda usar directamente una versión independiente de la aplicación o dotnet exec para iniciar la aplicación.

Vista del seguimiento capturado de dotnet-trace

En Windows, puede ver los archivos .nettrace en Visual Studio o PerfView para su análisis.

En Linux, puede ver el seguimiento cambiando el formato de salida de dotnet-trace a speedscope. Cambie el formato de archivo de salida mediante la opción -f|--format. Puede elegir entre nettrace (opción predeterminada) y speedscope. La opción -f speedscope hará que dotnet-trace produzca un archivo speedscope. Loa archivos Speedscope se pueden abrir en https://www.speedscope.app.

En el caso de los seguimientos recopilados en plataformas que no son Windows, también puede trasladar el archivo de seguimiento a un equipo Windows y verlo en Visual Studio o en PerfView.

Nota

El tiempo de ejecución de .NET Core genera seguimientos en el formato nettrace. Los seguimientos se convierten a formato speedscope (si se especifica) una vez completado el seguimiento. Dado que algunas conversiones pueden provocar la pérdida de datos, el archivo nettrace original se conserva junto al archivo convertido.

Uso del archivo. rsp para evitar escribir comandos largos

Puede iniciar dotnet-trace con un archivo .rsp que contenga los argumentos que se van a pasar. Esto puede ser útil cuando se habilitan proveedores que esperan argumentos largos o cuando se usa un entorno de shell que quita caracteres.

Por ejemplo, el proveedor siguiente puede resultar complicado de escribir cada vez que quiera realizar un seguimiento:

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

Además, el ejemplo anterior contiene " como parte del argumento. Dado que cada shell manipula las comillas de forma diferente, podría experimentar varios problemas al usar diferentes shells. Por ejemplo, el comando que se va a especificar en zsh es diferente del comando en cmd.

En lugar de escribirlo cada vez, puede guardar el siguiente texto en un archivo denominado 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

Cuando haya guardado myprofile.rsp, puede iniciar dotnet-trace con esta configuración con el siguiente comando:

dotnet-trace @myprofile.rsp

Consulte también