Utilitário de análise de despejo e depuração de processo dinâmico (dotnet-debug)

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

Observação

dotnet-debug atualmente, só dá suporte a aplicativos baseados em CoreCLR e atualmente não tem suporte no macOS.

Install

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

Sinopse

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

Description

A dotnet-debug ferramenta global permite que você anexe a processos dinâmicos do .NET e analise arquivos de despejo interativamente. Ao contrário dotnet-dumpde , que se concentra na coleta de despejo e na análise offline, dotnet-debug foi projetado para inspeção dinâmica do processo. Ele dá suporte a todos os mesmos comandos de depuração sos como dotnet-dump.

Essa ferramenta é útil em plataformas como o Alpine Linux, em que um trabalho lldb completo não está disponível. A dotnet-debug ferramenta executa comandos SOS para analisar o estado gerenciado e o diagnóstico de heap, mas não é um depurador nativo, portanto, não há suporte para exibir quadros de pilha nativos.

Opções

  • --version

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

  • -h|--help

    Mostra a ajuda da linha de comando.

Commands

Command
anexação dotnet-debug
dotnet-debug open-dump

anexação dotnet-debug

Anexa a um processo dinâmico e inicia um shell interativo com comandos de depuração para explorá-lo.

Sinopse

dotnet-debug attach <process-id> [-c|--commands <debug_command>] [--accept-license-agreement]

Arguments

  • <process-id>

    A ID do processo a ser anexada e analisada.

Opções

  • -c|--commands <debug_command>

    Executa os comandos na inicialização. Várias instâncias desse parâmetro podem ser utilizadas em uma invocação para encadear comandos. Os comandos são executados na ordem em que são fornecidos na linha de comando. Se você quiser dotnet-debug sair após os comandos, seu último comando deverá ser exit.

  • --accept-license-agreement

    Aceita o contrato de licenciamento sem solicitar.

Example

Anexar a um processo em execução com a ID 1234:

$ dotnet-debug attach 1234
Attaching to process: 1234 ...
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.
>

Execute um comando ao anexar e, em seguida, saia:

dotnet-debug attach 1234 -c clrstack -c exit

dotnet-debug open-dump

Inicia um shell interativo com comandos de depuração para explorar um arquivo de despejo.

Sinopse

dotnet-debug open-dump <dump_path> [-c|--commands] [--accept-license-agreement]

Arguments

  • <dump_path>

    O caminho para o arquivo de despejo a ser analisado.

Opções

  • -c|--commands <debug_command>

    Executa os comandos na inicialização. Várias instâncias desse parâmetro podem ser utilizadas em uma invocação para encadear comandos. Os comandos são executados na ordem em que são fornecidos na linha de comando. Se você quiser dotnet-debug sair após os comandos, seu último comando deverá ser exit.

  • --accept-license-agreement

    Aceita o contrato de licenciamento sem solicitar.

Example

Abra e analise um arquivo de despejo:

$ dotnet-debug open-dump ./core_20260209_135837
Loading dump: ./core_20260209_135837 ...
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.
>

Depurando comandos SOS

Os comandos e open-dump os attach comandos trazem uma sessão interativa que aceita os comandos SOS a seguir.

Command 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 CIL (linguagem intermediária comum) 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 do GC e imprime o nome do tipo e MethodTable a que 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 de coleta de lixo que pode 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 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, use 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

Para obter mais detalhes, consulte a Extensão de Depuração do SOS para .NET.

Usar dotnet-debug para anexar a um processo dinâmico

O exemplo a seguir mostra como anexar a um processo .NET em execução e investigar um problema de pool de threads:

$ dotnet-debug attach 1902
Attaching to process: 1902 ...
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)
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String)
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String)
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String)
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[])

Para ver uma exceção sem tratamento:

> 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
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d

StackTraceString: <none>
HResult: 80131604

dotnet-debug versus dotnet-dump

dotnet-debug e dotnet-dump compartilhe os mesmos comandos de depuração sos, mas atenda a diferentes finalidades primárias:

Característica dotnet-debug dotnet-dump
Anexar a um processo ao vivo ✔️ ❌
Coletar despejos ❌ ✔️
Analisar arquivos de despejo ✔️ ✔️
Listar processos do .NET (ps) ❌ ✔️

Use dotnet-debug quando precisar depurar um processo dinâmico interativamente. Use dotnet-dump quando precisar coletar despejos ou analisá-los offline.

Consulte também

  • Last updated on