Utilitário de coleta e análise de despejo (dotnet-dump)

  • Artigo

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

Observação

dotnet-dump para macOS só tem suporte no .NET 5 e versões posteriores.

Instalar

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

Observação

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>

Descrição

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

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 collect
dotnet-dump analyze
dotnet-dump ps

dotnet-dump collect

Captura um despejo 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 um despejo será coletado.

  • -n|--name <name>

    Especifica o nome do processo do qual será coletado um despejo.

  • --type <Full|Heap|Mini>

    Especifica o tipo de despejo, que determina os tipos de informações são coletados do processo. Há três tipos:

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

    Se não for especificado, o padrão será Full.

  • -o|--output <output_dump_path>

    O caminho completo e o nome do arquivo em que 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 no diretório especificado.

    Se não especificado:

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

    YYYMMDD é ano/mês/dia e HHMMSS é hora/minuto/segundos.

  • --diag

    Habilita o log de diagnóstico da coleção de despejo.

  • --crashreport

    Habilita a geração de relatório de falha.

Observação

No Linux e no macOS, esse comando espera que o aplicativo de destino e dotnet-dump compartilhem a mesma variável de ambiente TMPDIR. Caso contrário, o comando terá um tempo limite.

Observação

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

dotnet-dump analyze

Inicia um shell interativo para explorar um despejo. 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>

    Executar o comando na inicialização. Várias instâncias desse parâmetro podem ser utilizadas em uma invocação para encadear comandos. Os comandos serão executados na ordem em que forem fornecidos na linha de comando. Se você deseja que o despejo do dotnet saia após os comandos, seu último comando deverá ser 'exit'.

Analisar comandos SOS

Comando Função
analyzeoom Exibe as informações do último OOM ocorrido em uma solicitação de alocação para o heap da GC.
clrmodules Lista os módulos gerenciados no processo.
clrstack Fornece um rastreamento de pilha apenas do 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 log interno do SOS.
dso Exibe todos os objetos gerenciados encontradas 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áquina de estado assíncronas no heap com coleta de lixo.
dumpassembly Exibe detalhes sobre um assembly.
dumpclass Exibe informações sobre a estrutura EEClass no endereço especificado.
dumpconcurrentdictionary Exibe o conteúdo do 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 dentro de todos os AppDomains ou o especificado.
dumpgcdata Exibe informações sobre os dados da GC.
dumpgen Exibe o conteúdo do heap para a geração especificada.
dumpheap Exibe informações sobre o heap com coleta de lixo e as estatísticas de coleção 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 estrutura MethodDesc no endereço especificado.
dumpmodule Exibe informações sobre o módulo no endereço especificado.
dumpmt Exibe informações sobre a tabela do método no endereço especificado.
dumpobj Exibe informações sobre o objeto no endereço especificado.
dumpruntimetypes Localiza todos os objetos System.RuntimeType no heap da GC e imprime o nome do tipo e MethodTable a que eles também se referem.
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 encontradas 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 runtime internos.
eestack Executa dumpstack em todos os threads do processo.
eeversion Exibe informações sobre o runtime e as versões do SOS.
ehinfo Exibe os blocos de tratamento de exceções em um método com JIT.
exit ou quit Sai do modo interativo.
finalizequeue Exibe todos os objetos registrados para a finalização.
findappdomain Tenta resolver o AppDomain de um objeto GC.
gchandles Exibe estatísticas sobre identificadores 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) para o objeto no endereço especificado.
gcwhere Exibe o local no heap de GC do endereço especificado.
histclear Libera qualquer recurso usado pela família de comandos Hist.
histinit Inicializa as estruturas de SOS com base no log de estresse salvo no elemento a ser depurado.
histobj Examina todos os registros de realocação do log de estresse e exibe a cadeia de realocações da coleta de lixo que podem ter levado o endereço a ser 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 ambas as promoções e realocações da raiz especificada.
histstats Exibe as estatísticas do log de estresse.
ip2md Exibe a estrutura MethodDesc no endereço especificado no código compilado com JIT.
listnearobj Exibe o objeto anterior e posterior ao endereço especificado.
logopen Habilita o registro em log do arquivo de console.
logclose Desabilita o registro em log do arquivo de console.
logging Habilita/desabilita o log interno do SOS.
lm ou modules Exibe os módulos nativos no processo.
name2ee Exibe as estruturas MethodTable e EEClass do tipo ou do método especificado no módulo designado.
objsize Exibe o tamanho do objeto especificado.
parallelstacks Exibe a pilha de threads mesclados de maneira semelhante ao painel 'Pilhas Paralelas' do Visual Studio.
pathto Exibe o caminho da GC de <root> para <target>.
pe ou printexception Exibe e formata campos de qualquer objeto derivado da classe Exception no endereço especificado.
r ou registers Exibe os registros do thread.
runtimes Lista os runtimes no destino ou altera o runtime padrão.
setclrpath Define o caminho para carregar arquivos dac/dbi do coreclr usando setclrpath <path>.
setsymbolserver Habilita o suporte ao servidor de símbolos.
sos Executa vários comandos de depuração do coreclr. Use a sintaxe sos <command-name> <args>. Para obter mais informações, confira "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 de tarefa em um formato legível por humanos.
threadpool Exibe informações sobre o pool de threads de runtime.
threadpoolqueue Exibe itens de trabalho do pool de threads enfileirados.
threadstate O pretty imprime o significado de um estado de threads.
threads <threadid> ou setthread <threadid> Define ou exibe a ID do thread atual para os comandos SOS.
timerinfo Exibe informações sobre a execução de temporizadores.
token2ee Exibe a estrutura MethodTable e a estrutura MethodDesc para o token e o módulo especificados.
traverseheap Grava informações do heap em um arquivo em um formato compreendido pelo do criador de perfil do CLR.
verifyheap Verifica se há sinais de corrupção no heap do GC.
verifyobj Verifica o objeto passado como um argumento em busca de sinais de corrupção.

Observação

Detalhes adicionais podem ser encontrados na Extensão de Depuração do SOS para .NET.

dotnet-dump ps

Lista os processos de dotnet dos quais os despejos podem ser coletados. dotnet-dump versão 6.0.320703 e 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, execute o aplicativo de longa execução usando o comando dotnet-dump ps. A saída que você verá é a seguinte. Os argumentos de linha de comando, se houver, são mostrados no 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

Usando dotnet-dump

A primeira etapa é coletar um despejo. Essa etapa poderá ser ignorada se um despejo de núcleo já tiver sido gerado. O sistema operacional ou o recurso de geração de despejo interno do runtime do .NET Core podem criar despejos 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 despejo de núcleo com o 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.
>

Essa ação abre 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 sem tratamento 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 seja capaz de chamar ptrace. Se você estiver enfrentando problemas ao coletar despejos, o ambiente em que você está executando poderá estar configurado para restringir essas chamadas. Confira Despejos: perguntas frequentes para obter dicas de solução de problemas e possíveis soluções para problemas comuns.

Confira também