Partekatu bidez

Utilidad de análisis de rendimiento dotnet-trace

Este artículo se aplica a: ✔️ dotnet-trace 9.0.661903 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 dotnet-trace de , 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 | Brazo | Arm-x64
    Linux x64 | Brazo | 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.

  • Admite dos formas diferentes de recopilar seguimientos:

    • El collect verbo ofrece una funcionalidad coherente en cualquier sistema operativo.
    • El collect-linux verbo usa funcionalidades del sistema operativo específicas de Linux para proporcionar características adicionales.
    Característica collect collect-linux
    Sistemas operativos compatibles Cualquiera Solo Linux, versión >del kernel = 6.4
    Requiere privilegios de administrador o raíz No Sí
    Seguimiento de todos los procesos simultáneamente No Compatible
    Capturar eventos de kernel y biblioteca nativa No Compatible
    Las pila de llamadas de eventos incluyen marcos nativos No Sí

Opciones

  • -h|--help

    Muestra la ayuda de la línea de comandos.

  • --version

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

Comandos:

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

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

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. Esta opción solo se aplica cuando --clrevents se especifica y no se reemplaza por --profile o --providers. 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. Si el proveedor Microsoft-Windows-DotNETRuntime de tiempo de ejecución clR también está habilitado a través --providers de o --profile, esta opción se omite. 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
    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

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

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

    Inicia dotnet-dsrouter y se conecta a él. Requiere que dotnet-dsrouter esté instalado. Ejecute dotnet-dsrouter -h para obtener más información.

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

    Nota:

    En Linux y macOS, el uso de esta opción requiere la aplicación de destino y dotnet-trace compartir la misma TMPDIR variable de entorno. De lo contrario, se agotará el tiempo de espera del comando.

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

    Establece el puerto de diagnóstico usado para comunicarse con el proceso que se va a realizar el seguimiento. dotnet-trace y el entorno de ejecución de .NET dentro del proceso de destino deben aceptar la dirección del puerto, con una escucha y la otra conexión. dotnet-trace determina automáticamente el puerto correcto al adjuntar mediante las --process-id opciones o --name , o al iniciar un proceso mediante la -- <command> opción . Normalmente, solo es necesario especificar el puerto explícitamente al esperar un proceso que se iniciará en el futuro o comunicarse con un proceso que se ejecuta dentro de un contenedor que no forma parte del espacio de nombres del proceso actual.

    El port-address valor difiere en el sistema operativo:

    • Linux y macOS: una ruta de acceso a un socket de dominio unix, como /foo/tool1.socket.
    • Windows: una ruta de acceso a una canalización con nombre, como \\.\pipe\my_diag_port1.
    • Android, iOS y tvOS: un ip:puerto como 127.0.0.1:9000.

    De forma predeterminada, dotnet-trace escucha en la dirección especificada. Puede solicitar dotnet-trace que se conecte en su lugar anexando ,connect después de la dirección. Por ejemplo, --diagnostic-port /foo/tool1.socket,connect se conectará a un proceso en tiempo de ejecución de .NET que escucha el socket de /foo/tool1.socket dominio unix.

    Para obtener información sobre cómo usar esta opción para recopilar un seguimiento desde el inicio de la aplicación, consulte Uso del puerto de diagnóstico 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.

    Nota:

    En Linux y macOS, el uso de esta opción requiere la aplicación de destino y dotnet-trace compartir la misma TMPDIR variable de entorno. De lo contrario, se agotará el tiempo de espera del comando.

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

    Un perfil es un conjunto predefinido de configuraciones de proveedor para escenarios de seguimiento comunes. Se pueden especificar varios perfiles a la vez, delimitados por comas. Los proveedores configurados mediante --providers invalidan la configuración del perfil. Del mismo modo, si algún perfil configura el proveedor de tiempo de ejecución clR, invalidará las configuraciones prescritas a través --clreventsde .

    Cuando --profilese omiten , --providersy --clrevents , dotnet-trace collect habilita los perfiles dotnet-common y dotnet-sampled-thread-time de forma predeterminada.

    Perfiles disponibles:

    Perfil Descripción
    dotnet-common Diagnósticos ligeros en tiempo de ejecución de .NET diseñados para mantener una sobrecarga baja.
    Incluye eventos GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap y Compilation
    Equivalente a --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Muestra las pilas de subprocesos de .NET (~100 Hz) para identificar zonas activas a lo largo del tiempo. Usa el generador de perfiles de ejemplo en tiempo de ejecución con pilas administradas.
    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.
    database Captura ADO.NET y comandos de base de datos de Entity Framework.

    Nota:

    En versiones anteriores de la herramienta dotnet-trace, el verbo collect admitía un perfil denominado cpu-sampling. Este perfil se quitó porque el nombre era engañoso. Muestreó todos los subprocesos independientemente de su uso de CPU. Ahora puede lograr un resultado similar mediante --profile dotnet-sampled-thread-time,dotnet-common. Si necesita coincidir exactamente con el comportamiento anterior cpu-sampling , use --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

  • --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 <list-of-comma-separated-profile-names>. Si hay alguna incoherencia para un proveedor determinado, esta configuración tiene prioridad sobre la configuración implícita de --profile y --clrevents.

    Esta lista de proveedores tiene el 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 Microsoft-Windows-DotNETRuntime eventos.

  • --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 para detener el seguimiento al alcanzar el primer Method/JittingStarted evento emitido por el proveedor de Microsoft-Windows-DotNETRuntime eventos.

  • --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 para detener el seguimiento en el primer Method/JittingStarted evento del método OnButtonClick en el Program espacio de nombres emitido por el proveedor de Microsoft-Windows-DotNETRuntime eventos.

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

Nota:

El collect-linux verbo es una nueva característica de vista previa y se basa en una versión actualizada del formato de archivo .nettrace. La versión más reciente de PerfView admite estos archivos de seguimiento, pero es posible que todavía no funcionen otras formas de usar el archivo de seguimiento, como convert y report.

Recopila seguimientos de diagnóstico mediante perf_events, una tecnología de sistema operativo Linux. collect-linux habilita las siguientes características adicionales sobre collect.

recoger collect-linux
Sistemas operativos compatibles Cualquiera Solo Linux, versión >del kernel = 6.4
Requiere privilegios de administrador o raíz No Sí
Seguimiento de todos los procesos simultáneamente No Compatible
Capturar eventos de kernel y biblioteca nativa No Compatible
Las pila de llamadas de eventos incluyen marcos nativos No Sí

Prerrequisitos

  • Kernel de Linux compatible ( CONFIG_USER_EVENTS=y kernel 6.4+)
  • Permisos raíz
  • .NET 10+

Nota:

El collect-linux verbo solo se ejecuta en entornos linux x64 y linux arm64 que tienen glibc versión 2.35 o superior. Todas las distribuciones de Linux compatibles oficialmente con .NET 10 admiten este requisito excepto Alpine 3.22, CentOS Stream 9 y cualquier distribución basada en Red Hat Enterprise Linux 9. Una forma rápida de comprobar la versión de la libc de un sistema es con el comando ldd --version o ejecutando la biblioteca libc directamente.

Sinopsis

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]

Comportamiento de recopilación predeterminado

Cuando --providersno se especifican , --profile--clrevents, y --perf-events , collect-linux habilita estos perfiles de forma predeterminada:

  • dotnet-common : diagnósticos ligeros del entorno de ejecución de .NET.
  • cpu-sampling : muestreo de CPU del kernel.

De forma predeterminada, se realiza un seguimiento de todos los procesos de la máquina. Para realizar un seguimiento de un solo proceso, use -n, --name <name> o -p|--process-id <PID>.

Opciones

Opciones de especificación de proveedor/evento

  • --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 <list-of-comma-separated-profile-names>. Si hay alguna incoherencia para un proveedor determinado, esta configuración tiene prioridad sobre la configuración implícita de --profile y --clrevents.

    Esta lista de proveedores tiene el formato Provider[,Provider]:

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

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

  • --clreventlevel <clreventlevel>

    Nivel de detalle de los eventos CLR que se van a emitir. Esta opción solo se aplica cuando --clrevents se especifica y no se reemplaza por --profile o --providers. 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-linux --providers Microsoft-Windows-DotNETRuntime:3:4 solicita el mismo conjunto de eventos que dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Si el proveedor Microsoft-Windows-DotNETRuntime de tiempo de ejecución clR también está habilitado a través --providers de o --profile, esta opción se omite. 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
    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

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

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

    Lista separada por comas de eventos perf que se van a incluir en el seguimiento. Los eventos disponibles se pueden encontrar en tracefs, que normalmente se montan en /sys/kernel/tracing, a través available_events de para todos los eventos disponibles o a través del events/ subdirectorio para eventos clasificados.

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

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

    Un perfil es un conjunto predefinido de configuraciones de proveedor para escenarios de seguimiento comunes. Se pueden especificar varios perfiles a la vez, delimitados por comas. Los proveedores configurados mediante --providers invalidan la configuración del perfil. Del mismo modo, si algún perfil configura el proveedor de tiempo de ejecución clR, invalidará las configuraciones prescritas a través --clreventsde .

    Cuando --profilese omiten , --providers, --clreventsy --perf-events , dotnet-trace collect-linux habilita los perfiles dotnet-common y cpu-sampling de forma predeterminada.

    Perfiles disponibles:

    Perfil Descripción
    dotnet-common Diagnósticos ligeros en tiempo de ejecución de .NET diseñados para mantener una sobrecarga baja.
    Incluye eventos GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap y Compilation
    Equivalente a --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    cpu-sampling Muestreo de CPU de kernel (basado en rendimiento), emitido como Universal.Events/cpu, para la atribución precisa en la CPU.
    thread-time Conmutadores de contexto de subproceso de kernel, emitidos como Universal.Events/cswitch, para el análisis de la CPU y el programador.
    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.
    database Captura ADO.NET y comandos de base de datos de Entity Framework.

Opciones de recopilación de seguimiento

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

    Ruta de acceso de salida para los datos de seguimiento recopilados. Si no se especifica, el valor predeterminado es trace_<yyyyMMdd>_<HHmmss>.nettrace para el seguimiento predeterminado de toda la máquina y para <appname>_<yyyyMMdd>_<HHmmss>.nettrace un seguimiento específico del proceso (--name o --process-id)

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

Opciones de destino del proceso de .NET

Consulte Comportamiento de recopilación predeterminado.

  • -n, --name <name>

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

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

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

Opciones del modo de sondeo

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

    Sondee los procesos de .NET para admitir el comando IPC EventPipe UserEvents usado por collect-linux, sin recopilar un seguimiento. Primero se muestran los procesos admitidos en la lista de resultados. Use "-o stdout" para imprimir CSV (pid,processName,supportsCollectLinux) en la consola o "-o output-filename" para escribir el CSV. Sondee un único proceso con -n|--name o -p|-process-id.

    Como la ejecución collect-linux en modo de sondeo no recopila un seguimiento, no requiere permisos raíz para ejecutarse. No proporciona validación de los requisitos previos y los procesos de .NET que se ejecutan en versiones preliminares de .NET Runtime "10.0.0" no se admiten.

Nota:

Para recopilar un seguimiento mediante dotnet-trace collect-linux, debe ejecutarse con permisos raíz (/CAP_PERFMONCAP_SYS_ADMIN). De lo contrario, la herramienta no podrá recopilar eventos.

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]

informe dotnet-trace

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

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

    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.

  • Detenga la colección presionando la tecla Entrar . dotnet-trace finalizará el registro de eventos en el .nettrace archivo.

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

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

    El inicio de la aplicación con dotnet run puede ser problemático porque la CLI de dotnet puede generar muchos procesos secundarios que no son la aplicación y pueden conectarse a dotnet-trace antes de la aplicación, dejando que la aplicación 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.

(solo Linux) Recopilación de un seguimiento de toda la máquina mediante dotnet-trace

En este ejemplo se capturan ejemplos de CPU para todos los procesos de la máquina. Los procesos que ejecuten .NET 10+ también incluirán algunos eventos ligeros adicionales que describen el comportamiento de carga de GC, JIT y Ensamblado.

$ 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

En el caso de entornos con varias versiones de .NET instaladas, la ejecución collect-linux en modo de sondeo ayuda a distinguir si un proceso de .NET es capaz de realizar un seguimiento 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'

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

  • Last updated on