Partilhar via

Utilitário de recolha e análise de capturas (dotnet-dump)

  • Artigo

Este artigo aplica-se a: ✔️ dotnet-dump versão 3.0.47001 e versões posteriores

Nota

dotnet-dump para macOS só é suportado com .NET 5 e versões posteriores.

Instalar

Há duas maneiras de baixar e instalar dotnet-dump:

Nota

Para usar dotnet-dump em um aplicativo x86, você precisa de uma versão x86 correspondente da ferramenta.

Sinopse

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

Description

A dotnet-dump ferramenta global é uma maneira de coletar e analisar dumps no Windows, Linux e macOS sem nenhum depurador nativo envolvido. Esta ferramenta é importante em plataformas como o Alpine Linux, onde um totalmente funcional lldb não está disponível. A dotnet-dump ferramenta permite que você execute comandos SOS para analisar falhas e o coletor de lixo (GC), mas não é um depurador nativo, portanto, coisas como exibir quadros de pilha nativos não são suportadas.

Opções

  • --version

    Exibe a versão do utilitário dotnet-dump.

  • -h|--help

    Mostra a ajuda da linha de comando.

Comandos

Comando
dotnet-dump coletar
análise dotnet-dump
Dotnet-dump ps

dotnet-dump coletar

Captura um dump de um processo.

Sinopse

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

Opções

  • -h|--help

    Mostra a ajuda da linha de comando.

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

    Especifica o número de ID do processo do qual coletar um dump.

  • -n|--name <name>

    Especifica o nome do processo do qual coletar um dump.

  • --type <Full|Heap|Mini>

    Especifica o tipo de dump, que determina os tipos de informações coletadas do processo. Existem três tipos:

    • Full - O maior dump contendo toda a memória, incluindo as imagens do módulo.
    • Heap - Um dump grande e relativamente abrangente contendo listas de módulos, listas de threads, todas as pilhas, informações de exceção, informações de identificador e toda a memória, exceto imagens mapeadas.
    • Mini - Um pequeno dump contendo listas de módulos, listas de threads, informações de exceção e todas as pilhas.

    Se não for especificado, Full é o padrão.

  • -o|--output <output_dump_path>

    O caminho completo e o nome do arquivo onde o despejo coletado deve ser gravado. Verifique se o usuário sob o qual o processo dotnet está sendo executado tem permissões de gravação para o diretório especificado.

    Se não for especificado:

    • O padrão é .\dump_YYYYMMDD_HHMMSS.dmp no Windows.
    • O padrão é ./core_YYYYMMDD_HHMMSS no Linux e macOS.

    AAAAMMDD é Ano/Mês/Dia e HHMMSS é Hora/Minuto/Segundo.

  • --diag

    Habilita o log de diagnóstico de coleta de dump.

  • --crashreport

    Permite a geração de relatórios de falhas.

Nota

No Linux e macOS, este comando espera que o aplicativo de destino e dotnet-dump compartilhe a mesma TMPDIR variável de ambiente. Caso contrário, o comando atingirá o tempo limite.

Nota

Para coletar um dump usando dotnet-dumpo , ele precisa ser executado como o mesmo usuário que o usuário que executa o processo de destino ou como root. Caso contrário, a ferramenta não conseguirá estabelecer uma conexão com o processo de destino.

análise dotnet-dump

Inicia um shell interativo para explorar um dump. O shell aceita vários comandos SOS.

Sinopse

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

Argumentos

  • <dump_path>

    Especifica o caminho para o arquivo de despejo a ser analisado.

Opções

  • -c|--command <debug_command>

    Executa o comando ao iniciar. Várias instâncias desse parâmetro podem ser usadas em uma invocação para comandos em cadeia. Os comandos serão executados na ordem em que são fornecidos na linha de comando. Se você quiser que o dotnet dump saia após os comandos, seu último comando deve ser 'exit'.

Analisar comandos SOS

Comando Function
analyzeoom Exibe as informações do último OOM que ocorreu em uma solicitação de alocação para o heap GC.
clrmodules Lista os módulos gerenciados no processo.
clrstack Fornece um rastreamento de pilha somente de código gerenciado.
clrthreads Lista os threads gerenciados que estão em execução.
clru Exibe uma desmontagem anotada de um método gerenciado.
d ou readmemory Despeja o conteúdo da memória.
dbgout Habilita/desabilita (-off) o registro interno do SOS.
dso Exibe todos os objetos gerenciados encontrados dentro dos limites da pilha atual.
dumpalc Exibe detalhes sobre um AssemblyLoadContext colecionável para o qual o objeto especificado é carregado.
dumparray Exibe detalhes sobre uma matriz gerenciada.
dumpasync Exibe informações sobre máquinas de estado assíncronas na pilha coletada de lixo.
dumpassembly Exibe detalhes sobre uma montagem.
dumpclass Exibe informações sobre a EEClass estrutura no endereço especificado.
dumpconcurrentdictionary Exibe conteúdo de dicionário simultâneo.
dumpconcurrentqueue Exibe o conteúdo da fila simultânea.
dumpdelegate Exibe informações sobre um delegado.
dumpdomain Exibe informações sobre todos os assemblies em todos os AppDomains ou no especificado.
dumpgcdata Exibe informações sobre os dados GC.
dumpgen Exibe o conteúdo de pilha para a geração especificada.
dumpheap Exibe informações sobre a pilha coletada de lixo e estatísticas de coleta sobre objetos.
dumpil Exibe a linguagem intermediária comum (CIL) associada a um método gerenciado.
dumplog Grava o conteúdo de um log de estresse na memória no arquivo especificado.
dumpmd Exibe informações sobre a MethodDesc estrutura no endereço especificado.
dumpmodule Exibe informações sobre o módulo no endereço especificado.
dumpmt Exibe informações sobre a tabela de método no endereço especificado.
dumpobj Exibe informações do objeto no endereço especificado.
dumpruntimetypes Localiza todos os objetos System.RuntimeType no heap GC e imprime o nome do tipo e MethodTable a que eles se referem também.
dumpsig Despeja a assinatura de um método ou campo especificado por <sigaddr> <moduleaddr>.
dumpsigelem Despeja um único elemento de um objeto de assinatura.
dumpstackobjects Exibe todos os objetos gerenciados encontrados dentro dos limites da pilha atual.
dumpvc Exibe informações sobre os campos de uma classe de valor.
eeheap Exibe informações sobre a memória de processo consumida por estruturas de dados de tempo de execução internas.
eestack É executado dumpstack em todos os threads no processo.
eeversion Exibe informações sobre as versões de tempo de execução e SOS.
ehinfo Exibe os blocos de tratamento de exceção em um método JIT-ed.
exit ou quit Sai do modo interativo.
finalizequeue Exibe todos os objetos registrados para finalização.
findappdomain Tenta resolver o AppDomain de um objeto GC.
gchandles Exibe estatísticas sobre as alças do coletor de lixo no processo.
gcheapstat Exibe estatísticas sobre o coletor de lixo.
gcinfo Exibe a codificação JIT GC para um método.
gcroot Exibe informações sobre referências (ou raízes) ao objeto no endereço especificado.
gcwhere Exibe o local no heap GC do endereço especificado.
histclear Libera todos os recursos usados pela família de comandos Hist.
histinit Inicializa as estruturas SOS a partir do log de estresse salvo no depurador.
histobj Examina todos os registros de realocação de log de estresse e exibe a cadeia de relocações de coleta de lixo que podem ter levado ao endereço passado como um argumento.
histobjfind Exibe todas as entradas de log que fazem referência ao objeto no endereço especificado.
histroot Exibe informações relacionadas a promoções e realocações da raiz especificada.
histstats Exibe estatísticas de log de estresse.
ip2md Exibe a MethodDesc estrutura no endereço especificado no código que foi compilado em JIT.
listnearobj Exibe o objeto que precede e sucede o endereço especificado.
logopen Habilita o registro em log de arquivos do console.
logclose Desabilita o log de arquivos do console.
logging Habilita/desabilita o registro interno de SOS.
lm ou modules Exibe os módulos nativos no processo.
name2ee Exibe as MethodTable estruturas e EEClass para o tipo ou método especificado no módulo especificado.
objsize Exibe o tamanho do objeto especificado.
parallelstacks Exibe a pilha de threads mesclados de forma semelhante ao painel 'Pilhas paralelas' do Visual Studio.
pathto Exibe o caminho GC de <root> para <target>.
pe ou printexception Exibe e formata campos de qualquer objeto derivado da Exception classe no endereço especificado.
r ou registers Exibe os registros do thread.
runtimes Lista os tempos de execução no destino ou altera o tempo de execução padrão.
setclrpath Define o caminho para carregar arquivos coreclr dac/dbi usando setclrpath <path>o .
setsymbolserver Habilita o suporte ao servidor de símbolos.
sos Executa vários comandos de depuração coreclr. Use a sintaxe sos <command-name> <args>. Para obter mais informações, consulte 'soshelp'.
soshelp ou help Exibe todos os comandos disponíveis.
soshelp <command> ou help <command> Exibe o comando especificado.
syncblk Exibe as informações do titular do SyncBlock.
taskstate Exibe um estado Task em um formato legível por humanos.
threadpool Exibe informações sobre o pool de threads de tempo de execução.
threadpoolqueue Exibe itens de trabalho do pool de threads enfileirados.
threadstate Pretty imprime o significado de um estado de threads.
threads <threadid> ou setthread <threadid> Define ou exibe o ID de thread atual para os comandos SOS.
timerinfo Exibe informações sobre temporizadores em execução.
token2ee Exibe a estrutura MethodTable e a estrutura MethodDesc para o token e o módulo especificados.
traverseheap Grava informações de pilha em um arquivo em um formato compreendido pelo CLR Profiler.
verifyheap Verifica a pilha GC em busca de sinais de corrupção.
verifyobj Verifica o objeto que é passado como um argumento para sinais de corrupção.

Nota

Detalhes adicionais podem ser encontrados em SOS Debugging Extension for .NET.

Dotnet-dump ps

Lista os processos dotnet dos quais os dumps podem ser coletados. dotnet-dump A versão 6.0.320703 e versões posteriores também exibem os argumentos de linha de comando com os quais cada processo foi iniciado, se disponível.

Sinopse

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

Exemplo

Suponha que você inicie um aplicativo de longa execução usando o comando dotnet run --configuration Release. Em outra janela, você executa o dotnet-dump ps comando. A saída que você verá é a seguinte. Os argumentos de linha de comando, se houver, são mostrados na dotnet-dump versão 6.0.320703 e posterior.

> dotnet-dump ps

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

Ao utilizar dotnet-dump

O primeiro passo é recolher um lixão. Esta etapa pode ser ignorada se um dump principal já tiver sido gerado. O sistema operacional ou o recurso de geração de despejo interno do tempo de execução do .NET Core podem criar dumps principais.

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

Agora analise o dump principal com o analyze comando:

$ 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 ação apresenta uma sessão interativa que aceita comandos como:

> 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 uma exceção não tratada que matou seu aplicativo:

> 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

Solução de problemas de coleta de despejo

A coleta de despejo requer que o processo possa chamar ptrace. Se você estiver enfrentando problemas para coletar dumps, o ambiente em que você está executando pode ser configurado para restringir essas chamadas. Consulte nossos Dumps: FAQ para obter dicas de solução de problemas e possíveis soluções para problemas comuns.

Consulte também