Ferramenta de análise de heap (dotnet-gcdump)

Este artigo se aplica ao: ✔️ dotnet-gcdump versão 3.1.57502 e versões posteriores

Instalar

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

• Ferramenta global dotnet:

  Para instalar a última versão de lançamento do dotnet-gcdumppacote NuGet, use o comando dotnet tool install:

  dotnet tool install --global dotnet-gcdump
  

• Download direto:

  Baixe o executável da ferramenta que corresponde à sua plataforma:

  Sistema operacional	Plataforma
  Windows	x86 | x64 | Arm | Arm64
  Linux	x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Observação

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

Sinopse

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

Descrição

A ferramenta global dotnet-gcdump coleta despejos de GC (Coletor de Lixo) de processos .NET ao vivo usando EventPipe. Os despejos de GC são criados disparando um GC no processo de destino, ativando eventos especiais e regenerando o grafo de raízes de objeto do fluxo de eventos. Esse processo permite que despejos de GC sejam coletados enquanto o processo está em execução e com sobrecarga mínima. Esses despejos são úteis para vários cenários:

• Comparar o número de objetos no heap em vários pontos no tempo.
• Analisar raízes de objetos (respondendo a perguntas como: "O que ainda tem uma referência a esse tipo?").
• Coletar estatísticas gerais sobre as contagens de objetos no heap.

Exibir o despejo de GC capturado de dotnet-gcdump

No Windows, arquivos .gcdump podem ser exibidos no PerfView para análise ou no Visual Studio. Atualmente, não há nenhuma maneira de abrir uma .gcdump em plataformas que não sejam Windows.

Você pode coletar vários .gcdumps e abri-los simultaneamente no Visual Studio para obter uma experiência de comparação.

Opções

• --version

  Exibe a versão do serviço dotnet-gcdump.

• -h|--help

  Mostra a ajuda da linha de comando.

Comandos

Comando
dotnet-gcdump collect
dotnet-gcdump ps
dotnet-gcdump report

dotnet-gcdump collect

Coleta um despejo de GC de um processo em execução no momento.

Aviso

Para percorrer o heap do GC, esse comando dispara uma coleta de lixo de geração 2 (completa), que pode suspender o runtime por um longo tempo, especialmente quando o heap do GC é grande. Não use esse comando em ambientes sensíveis ao desempenho quando o heap do GC for grande.

Sinopse

dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-file-path>] [-v|--verbose] [-t|--timeout <timeout>] [-n|--name <name>]

Opções

• -h|--help

  Mostra a ajuda da linha de comando.

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

  A ID do processo do qual coletar o despejo de GC.

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

  O caminho onde os despejos de GC coletados devem ser gravados. O padrão é .\YYYYMMDD_HHMMSS_<pid.gcdump>.

• -v|--verbose

  Gere o log durante a coleta do despejo de GC.

• -t|--timeout <timeout>

  Desista de coletar o despejo de GC se demorar mais do que esses vários segujndos. O valor padrão é 30.

• -n|--name <name>

  O nome do processo do qual coletar o despejo de GC.

Observação

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

Observação

Para coletar um despejo de GC usando dotnet-gcdump, 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-gcdump ps

Lista os processos de dotnet para os quais os despejos de GC podem ser coletados. dotnet-gcdump 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-gcdump 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-gcdump ps. A saída que você verá é a seguinte. Os argumentos de linha de comando, se houver, são mostrados usando dotnet-gcdump versão 6.0.320703 e posterior.

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

dotnet-gcdump report <gcdump_filename>

Gerar um relatório de um despejo de GC gerado anteriormente ou de um processo em execução e gravar em stdout.

Sinopse

dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <HeapStat>]

Opções

• -h|--help

  Mostra a ajuda da linha de comando.

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

  A ID do processo do qual coletar o despejo de GC.

• -t|--report-type <HeapStat>

  O tipo de relatório a ser gerado. Opções disponíveis: heapstat (padrão).

Solucionar problemas

• Não há informações de tipo no gcdump.

  Antes do .NET Core 3.1, havia um problema em que um cache de tipo não era limpo entre gcdumps quando eles eram invocados com EventPipe. Isso resultava nos eventos necessários para determinar que as informações de tipo não eram enviadas para o segundo e posterior gcdumps. Isso foi corrigido no .NET Core 3.1-preview2.

• COM e tipos estáticos não estão no despejo de GC.

  Antes do .NET Core 3.1, havia um problema em que tipos estáticos e COM não eram enviados quando o despejo de GC era invocado por meio do EventPipe. Isso foi corrigido no .NET Core 3.1.

• dotnet-gcdump não consegue gerar um arquivo .gcdump devido a informações ausentes, por exemplo, [Error] Exception during gcdump: System.ApplicationException: o arquivo ETL mostra o início de um despejo de heap, mas não sua conclusão. Ou o arquivo .gcdump não inclui o heap inteiro.

  dotnet-gcdump funciona coletando um rastreamento de eventos emitidos pelo coletor de lixo durante uma coleta de geração 2 induzido. Se o heap for suficientemente grande ou não houver memória suficiente para dimensionar os buffers de evento, os eventos necessários para reconstruir o gráfico de heap do rastreamento poderão ser descartados. Nesse caso, para diagnosticar problemas com o heap, é recomendável coletar um despejo do processo.

• dotnet-gcdump parece causar um problema de memória insuficiente em um ambiente com restrição de memória.

  dotnet-gcdump funciona coletando um rastreamento de eventos emitidos pelo coletor de lixo durante uma coleta de geração 2 induzido. O buffer da coleção de eventos pertence ao aplicativo de destino e pode crescer até 256 MB. o próprio dotnet-gcdump também usa memória. Se o ambiente for restrito à memória, certifique-se de considerar esses fatores ao coletar um gcdump para evitar erros.