Utilidad de recopilación y análisis de volcado de memoria (dotnet-dump)

  • Artículo

Este artículo se aplica a: ✔️ dotnet-dump versión 3.0.47001 y posteriores

Nota

dotnet-dump para macOS solo se admite con .NET 5 y versiones posteriores.

Instalar

Hay dos maneras de descargar e instalar dotnet-dump:

  • Herramienta global dotnet:

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

    dotnet tool install --global dotnet-dump

  • 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

Nota

Para usar dotnet-dump en una aplicación x86, necesita la versión x86 correspondiente de la herramienta.

Sinopsis

dotnet-dump [-h|--help] [--version] <command>

Descripción

La herramienta global dotnet-dump es una forma de recopilar y analizar volcados en Windows, Linux y macOS sin necesidad de ningún depurador nativo. Esta herramienta es importante en plataformas como Alpine Linux, donde no está disponible una versión de lldb totalmente operativa. La herramienta dotnet-dump permite ejecutar comandos SOS para analizar bloqueos y el recolector de elementos no utilizados (GC), pero no es un depurador nativo, por lo que no se admiten elementos como la visualización de marcos de pila nativos.

Opciones

  • --version

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

  • -h|--help

    Muestra la ayuda de la línea de comandos.

Comandos

Comando
dotnet-dump collect
dotnet-dump analyze
dotnet-dump ps

dotnet-dump collect

Captura un volcado de un proceso.

Sinopsis

dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--output] [--diag] [--crashreport]

Opciones

  • -h|--help

    Muestra la ayuda de la línea de comandos.

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

    Especifica el número de id. de proceso del que se va a recopilar un volcado.

  • -n|--name <name>

    Especifica el nombre del proceso del que se va a recopilar un volcado.

  • --type <Full|Heap|Mini>

    Especifica el tipo de volcado, que determina los tipos de información que se recopilan del proceso. Existen tres tipos:

    • Full: el volcado más grande que contiene toda la memoria, incluidas las imágenes de los módulos.
    • Heap: un volcado grande y relativamente completo que contiene listas de módulos, listas de subprocesos, todas las pilas, información de excepción, información de control y toda la memoria excepto las imágenes asignadas.
    • Mini: un volcado pequeño que contiene listas de módulos, listas de subprocesos, información de excepción y todas las pilas.

    Si no se especifica, el valor predeterminado es Full.

  • -o|--output <output_dump_path>

    La ruta de acceso completa y el nombre de archivo donde se debe escribir el volcado recopilado. Asegúrese de que el usuario con el que se ejecuta el proceso dotnet tiene permisos de escritura en el directorio especificado.

    Si no se especifica:

    • El valor predeterminado es .\dump_AAAAMMDD_HHMMSS.dmp en Windows.
    • El valor predeterminado es ./core_AAAAMMDD_HHMMSS en Linux o macOS.

    AAAAMMDD es año/mes/día y HHMMSS es hora/minuto/segundo.

  • --diag

    Habilita el registro de diagnóstico de la recopilación de volcado.

  • --crashreport

    Habilita la generación de informes de bloqueo.

Nota

En Linux y macOS, este comando espera que la aplicación de destino y dotnet-dump compartan la misma variable de entorno TMPDIR. De lo contrario, se agotará el tiempo de espera del comando.

Nota

Para recopilar un volcado mediante dotnet-dump, 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.

dotnet-dump analyze

Inicia un shell interactivo para explorar un volcado. El shell acepta varios comandos SOS.

Sinopsis

dotnet-dump analyze <dump_path> [-h|--help] [-c|--command]

Argumentos

  • <dump_path>

    Especifica la ruta de acceso al archivo de volcado que se va a analizar.

Opciones

  • -c|--command <debug_command>

    Ejecuta el comando al iniciarse. Se pueden usar varias instancias de este parámetro en una invocación para encadenar comandos. Los comandos se ejecutarán en el orden en que se proporcionan en la línea de comandos. Si desea que el volcado de dotnet salga después de los comandos, el último comando debe ser "exit".

Análisis de comandos SOS

Comando Función
analyzeoom Muestra la información del último OOM que se produjo en una solicitud de asignación al montón de GC.
clrmodules Enumera los módulos administrados en el proceso.
clrstack Proporciona un seguimiento de pila del código administrado únicamente.
clrthreads Enumera los subprocesos administrados que se están ejecutando.
clru Muestra un desensamblado anotado de un método administrado.
d o readmemory Vuelca el contenido de la memoria.
dbgout Habilita o deshabilita el registro de SOS interno (-off).
dso Muestra todos los objetos administrados que se han encontrado dentro de los límites de la pila actual.
dumpalc Muestra detalles sobre un AssemblyLoadContext recopilable al que se carga el objeto especificado.
dumparray Muestra detalles sobre una matriz administrada.
dumpasync Muestra información sobre las máquinas de estados asincrónicas en el montón de recolección de elementos no utilizados.
dumpassembly Muestra detalles sobre un ensamblado.
dumpclass Muestra información sobre la estructura EEClass en la dirección especificada.
dumpconcurrentdictionary Muestra el contenido del diccionario simultáneo.
dumpconcurrentqueue Muestra el contenido de la cola simultánea.
dumpdelegate Muestra información sobre un delegado.
dumpdomain Muestra información acerca de todos los ensamblados dentro de los dominios de aplicación o el dominio especificado.
dumpgcdata Muestra información sobre los datos de GC.
dumpgen Muestra el contenido del montón para la generación especificada.
dumpheap Muestra información sobre el montón de recolección de elementos no utilizados y estadísticas de recolección de los objetos.
dumpil Muestra el lenguaje intermedio común (CIL) asociado a un método administrado.
dumplog Escribe el contenido de un registro de esfuerzo existente en memoria en el archivo especificado.
dumpmd Muestra información sobre la estructura MethodDesc en la dirección especificada.
dumpmodule Muestra información sobre el módulo en la dirección especificada.
dumpmt Muestra información sobre la tabla de métodos en la dirección especificada.
dumpobj Muestra información sobre el objeto en la dirección especificada.
dumpruntimetypes Busca todos los objetos System.RuntimeType en el montón de GC e imprime el nombre de tipo y MethodTable al que hacen referencia.
dumpsig Vuelca la firma de un método o campo especificado por <sigaddr> <moduleaddr>.
dumpsigelem Vuelca un único elemento de un objeto de firma.
dumpstackobjects Muestra todos los objetos administrados que se han encontrado dentro de los límites de la pila actual.
dumpvc Muestra información sobre los campos de una clase de valor.
eeheap Muestra información sobre la memoria de proceso que usan las estructuras de datos internas del runtime.
eestack Ejecuta el comando dumpstack en todos los subprocesos del proceso.
eeversion Muestra información sobre el tiempo de ejecución y las versiones SOS.
ehinfo Muestra los bloques de control de excepciones de un método JIT.
exit o quit Sale del modo interactivo.
finalizequeue Muestra todos los objetos registrados para su finalización.
findappdomain Intenta resolver el dominio de aplicación de un objeto GC.
gchandles Muestra estadísticas acerca de los identificadores del recolector de elementos no utilizados existentes en el proceso.
gcheapstat Muestra estadísticas sobre el recolector de elementos no utilizados.
gcinfo Muestra la codificación JIT de recolección de elementos no utilizados para un método.
gcroot Muestra información sobre las referencias (o raíces) al objeto en la dirección especificada.
gcwhere Muestra la ubicación en el montón de recolección de elementos no utilizados de la dirección especificada.
histclear Libera los recursos usados por la familia de comandos Hist.
histinit Inicializa las estructuras SOS del registro de esfuerzo guardado en el código que se está depurando.
histobj Examina todos los registros de reubicación del registro de esfuerzo y muestra la cadena de reubicaciones de recolección de elementos no utilizados que pueden haber conducido a la dirección que se ha pasado como argumento.
histobjfind Muestra todas las entradas de registro que hacen referencia al objeto en la dirección especificada.
histroot Muestra información relacionada con las promociones y las reubicaciones de la raíz especificada.
histstats Muestra las estadísticas del registro de esfuerzo.
ip2md Muestra la estructura MethodDesc en la dirección especificada en el código compilado JIT.
listnearobj Muestra los objetos anteriores y posteriores a la dirección especificada.
logopen Habilita el registro de archivos de la consola.
logclose Deshabilita el registro de archivos de la consola.
logging Habilita o deshabilita el registro de SOS interno.
lm o modules Muestra los módulos nativos del proceso.
name2ee Muestra las estructuras MethodTable y EEClass para el tipo o método especificado del módulo indicado.
objsize Muestra el tamaño del objeto especificado.
parallelstacks Muestra la pila de subprocesos combinados de forma similar al panel "Pilas paralelas" de Visual Studio.
pathto Muestra la ruta de acceso de GC de <root> a <target>.
pe o printexception Muestra y da formato a los campos de cualquier objeto derivado de la clase Exception en la dirección especificada.
r o registers Muestra los registros del subproceso.
runtimes Enumera los runtimes en el destino o cambia el runtime predeterminado.
setclrpath Establece la ruta de acceso para cargar archivos dac o dbi de CoreCLR mediante setclrpath <path>.
setsymbolserver Habilita la compatibilidad con el servidor de símbolos.
sos Ejecuta varios comandos de depuración de CoreCLR. Usa la sintaxis sos <command-name> <args>. Para obtener más información, vea "soshelp".
soshelp o help Muestra todos los comandos disponibles.
soshelp <command> o help <command> Muestra el comando especificado.
syncblk Muestra la información del contenedor de SyncBlock.
taskstate Muestra un estado de tarea en un formato legible para el ser humano.
threadpool Muestra información sobre el grupo de subprocesos de runtime.
threadpoolqueue Muestra los elementos de trabajo del grupo de subprocesos en cola.
threadstate Imprime el significado de un estado de subprocesos.
threads <threadid> o setthread <threadid> Establece o muestra el identificador del subproceso actual para los comandos SOS.
timerinfo Muestra información sobre los temporizadores de ejecución.
token2ee Muestra la estructura MethodTable y la estructura MethodDesc para el token y el módulo especificados.
traverseheap Escribe información del montón en el archivo especificado, en un formato reconocido por el CLR Profiler.
verifyheap Comprueba el montón de GC para ver si hay signos de daños.
verifyobj Comprueba el objeto que se pasa como argumento en busca de indicios de daños.

Nota

Puede encontrar más detalles en Extensión de depuración de SOS para .NET.

dotnet-dump ps

Enumera los procesos de dotnet de los que se pueden recolectar volcados de memoria. dotnet-dump versión 6.0.320703 y posteriores. También muestra los argumentos de la línea de comandos con los que se ha iniciado cada proceso, si está disponible.

Sinopsis

dotnet-dump 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-dump ps. La salida que se ve es la siguiente. Los argumentos de la línea de comandos, si los hay, se muestran en dotnet-dump versión 6.0.320703 y posteriores.

> dotnet-dump ps

  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

Uso de dotnet-dump

El primer paso es recopilar un volcado. Este paso se puede omitir si ya se ha generado un volcado principal. El sistema operativo o la característica de generación de volcado integrada del runtime de .NET Core pueden crear volcados principales.

$ dotnet-dump collect --process-id 1902
Writing minidump to file ./core_20190226_135837
Written 98983936 bytes (24166 pages) to core file
Complete

Ahora analice el volcado principal con el comando analyze:

$ dotnet-dump analyze ./core_20190226_135850
Loading core dump: ./core_20190226_135850
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

Esta acción abre una sesión interactiva que acepta comandos como los siguientes:

> clrstack
OS Thread Id: 0x573d (0)
    Child SP               IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]

Para ver una excepción no controlada que ha terminado la aplicación:

> pe -lines
Exception object: 00007fb18c038590
Exception type:   System.Reflection.TargetInvocationException
Message:          Exception has been thrown by the target of an invocation.
InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP               IP               Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]

StackTraceString: <none>
HResult: 80131604

Solución de problemas de recopilación de volcados de memoria

La recopilación de volcados de memoria requiere que el proceso pueda llamar a ptrace. Si tiene problemas para recopilar volcados de memoria, es posible que su entorno de ejecución esté configurado para restringir ese tipo de llamadas. Consulte nuestras preguntas más frecuentes sobre volcados de memoria para obtener sugerencias de solución de problemas y posibles soluciones a problemas comunes.

Vea también