Compartilhar via

Utilitário de análise de desempenho dotnet-trace

  • Artigo

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

Instalar

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

Sinopse

dotnet-trace [-h, --help] [--version] <command>

Descrição

A ferramenta dotnet-trace:

  • É uma ferramenta .NET Core multiplataforma.
  • Habilita a coleção de rastreamentos do .NET Core de um processo em execução sem um criador de perfil nativo.
  • É criado no EventPipe do runtime do .NET Core.
  • Oferece a mesma experiência no Windows, Linux ou macOS.

Opções

  • -h|--help

    Mostra a ajuda da linha de comando.

  • --version

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

  • --duration

    Quanto tempo é necessário para executar o rastreamento? --duration 00:00:00:05 fará a execução por 5 segundos.

Comandos

Comando
dotnet-trace collect
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace report

dotnet-trace collect

Coleta um rastreamento de diagnóstico de um processo em execução ou inicia um processo filho e o rastreia (somente .NET 5+). Para que a ferramenta execute um processo filho e rastreie-o de sua inicialização, acrescente -- ao comando coletar.

Sinopse

dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--clrevents <clrevents>]
    [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [--duration dd:hh:mm:ss]
    [-n, --name <name>] [--diagnostic-port] [-o|--output <trace-file-path>] [-p|--process-id <pid>]
    [--profile <profile-name>] [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io] [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

Opções

  • --buffersize <size>

    Define o tamanho do buffer na memória em megabytes. O padrão é 256 MB.

    Observação

    Se o processo de destino emitir eventos mais rápido do que possam ser gravados em disco, esse buffer pode estourar e alguns eventos serão descartados. Você pode mitigar esse problema aumentando o tamanho do buffer ou reduzindo o número de eventos que estão sendo registrados.

  • --clreventlevel <clreventlevel>

    Verbosidade de eventos CLR a serem emitidos. A tabela a seguir mostra os níveis de eventos disponíveis.

    Valor da cadeia de caracteres Valor numérico
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Uma lista de palavras-chave do provedor de runtime CLR para habilitar separado por sinais +. Esse é um mapeamento simples que permite especificar palavras-chave de evento por meio de aliases de cadeia de caracteres em vez de seus valores hexadecimais. Por exemplo, dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 solicita o mesmo conjunto de eventos que dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. A tabela abaixo mostra a lista de palavras-chave disponíveis:

    Alias de cadeia de caracteres de palavra-chave Valor hexadecimal da palavra-chave
    gc 0x1
    gchandle 0x2
    fusion 0x4
    loader 0x8
    jit 0x10
    ngen 0x20
    startenumeration 0x40
    endenumeration 0x80
    security 0x400
    appdomainresourcemanagement 0x800
    jittracing 0x1000
    interop 0x2000
    contention 0x4000
    exception 0x8000
    threading 0x10000
    jittedmethodiltonativemap 0x20000
    overrideandsuppressngenevents 0x40000
    type 0x80000
    gcheapdump 0x100000
    gcsampledobjectallocationhigh 0x200000
    gcheapsurvivalandmovement 0x400000
    gcheapcollect 0x800000
    gcheapandtypenames 0x1000000
    gcsampledobjectallocationlow 0x2000000
    perftrack 0x20000000
    stack 0x40000000
    threadtransfer 0x80000000
    debugger 0x100000000
    monitoring 0x200000000
    codesymbols 0x400000000
    eventsource 0x800000000
    compilation 0x1000000000
    compilationdiagnostic 0x2000000000
    methoddiagnostic 0x4000000000
    typediagnostic 0x8000000000

    Você pode ler mais detalhadamente sobre o provedor CLR na Documentação de referência do provedor de runtime do .NET.

  • --format {Chromium|NetTrace|Speedscope}

    Define o formato de saída para a conversão do arquivo de rastreamento. O padrão é NetTrace.

  • -n, --name <name>

    O nome do processo do qual coletar o rastreamento.

  • --diagnostic-port <path-to-port>

    O nome da porta de diagnóstico a ser criada. Consulte Usar a porta de diagnóstico para coletar um rastreamento da inicialização do aplicativo para saber como usar essa opção para coletar um rastreamento da inicialização do aplicativo.

  • --duration <time-to-run>

    O tempo para o rastreamento ser executado. Use o formato dd:hh:mm:ss. Por exemplo 00:00:00:05 fará a execução por 5 segundos.

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

    O caminho de saída para os dados de rastreamento coletados. Se não for especificado, o padrão será <appname>_<yyyyMMdd>_<HHmmss>.nettrace. Por exemplo, “myapp_20210315_111514.nettrace”.

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

    ID do processo do qual coletar o rastreamento.

  • --profile <profile-name>

    Um conjunto predefinido nomeado de configurações de provedor que permite que cenários comuns de rastreamento sejam especificados de forma sucinta. Os perfis a seguir estão disponíveis:

Perfil Descrição
cpu-sampling Útil para acompanhar o uso da CPU e as informações gerais de runtime do .NET. Essa será a opção padrão se nenhum perfil ou provedor for especificado.
gc-verbose Rastreia coleções GC e exemplos de alocações de objeto.
gc-collect Rastreia coleções de GC apenas com uma sobrecarga muito baixa.

  • --providers <list-of-comma-separated-providers>

    Uma lista separada por vírgulas de provedores EventPipe a serem habilitados. Esses provedores complementam todos os provedores implícitos por --profile <profile-name>. Se houver alguma inconsistência para um provedor específico, essa configuração terá precedência sobre a configuração implícita do perfil.

    Esta lista de provedores está no formato:

    • Provider[,Provider]
    • Provider está no formato: KnownProviderName[:Flags[:Level][:KeyValueArgs]].
    • KeyValueArgs está no formato: [key1=value1][;key2=value2].

    Para saber mais sobre alguns dos provedores conhecidos no .NET, consulte Provedores de eventos conhecidos.

  • -- <command> (para aplicativos de destino que executam somente .NET 5 ou posterior)

    Após os parâmetros de configuração de coleção, o usuário pode acrescentar -- seguido por um comando para iniciar um aplicativo .NET com pelo menos um runtime 5.0. Isso pode ser útil ao diagnosticar problemas que ocorrem no início do processo, como problemas de desempenho de inicialização ou erros de carregador de assembly e associador.

    Observação

    O uso dessa opção monitora o primeiro processo do .NET que se comunica de volta com a ferramenta, o que significa que, se o comando iniciar vários aplicativos .NET, ele coletará apenas o primeiro aplicativo. Portanto, é recomendável usar essa opção em aplicativos autocontidos ou usar a opção dotnet exec <app.dll>.

  • --show-child-io

    Mostra os fluxos de entrada e saída de um processo filho iniciado no console atual.

  • --resume-runtime

    Retomar o runtime após a inicialização da sessão. O padrão será true. Disable resume of runtime using --resume-runtime:false.

  • --stopping-event-provider-name

    Uma cadeia de caracteres, analisada como está, que interromperá o rastreamento quando houver um evento com o nome do provedor correspondente. Para um evento de parada mais específico, forneça --stopping-event-event-name adicionalmente e/ou --stopping-event-payload-filter. Por exemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime para interromper o rastreamento no primeiro evento emitido pelo provedor de eventos Microsoft-Windows-DotNETRuntime.

  • --stopping-event-event-name

    Uma cadeia de caracteres, analisada como está, que interromperá o rastreamento quando houver um evento com o nome do evento correspondente. Requer a definição de --stopping-event-provider-name. Para um evento de parada mais específico, forneça --stopping-event-payload-filter adicionalmente. Por exemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted para interromper o rastreamento no primeiro evento Method/JittingStarted emitido pelo provedor de eventos Microsoft-Windows-DotNETRuntime.

  • --stopping-event-payload-filter

    Uma cadeia de caracteres, analisada como pares [payload_field_name]:[payload_field_value] separados por vírgulas, que interromperá o rastreamento quando houver um evento contendo todos os pares de payload especificados. Requer a definição de --stopping-event-provider-name e --stopping-event-event-name. Por exemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick para interromper o rastreamento no primeiro evento Method/JittingStarted do método OnButtonClick no namespace Program emitido pelo provedor de eventos Microsoft-Windows-DotNETRuntime.

Observação

  • Parar o rastreamento pode levar muito tempo (até minutos) para aplicativos grandes. O runtime precisa enviar o cache de tipo para todo o código gerenciado que foi capturado no rastreamento.
  • No Linux e no macOS, esse comando espera que o aplicativo de destino e dotnet-trace compartilhem a mesma variável de ambiente TMPDIR. Caso contrário, o comando terá um tempo limite.
  • Para coletar um rastreamento usando dotnet-trace, 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.
  • Se você tiver uma exceção sem tratamento durante a execução de dotnet-trace collect, resultará em um rastreamento quebrado. Se encontrar a causa raiz da exceção for sua prioridade, navegue até Coletar despejos em caso de falha. Como resultado da exceção sem tratamento, o rastreamento é truncado quando o runtime é desligado para evitar outros comportamentos indesejados, como um travamento ou corrupção de dados. Mesmo que o rastreamento esteja quebrado, você ainda pode abri-lo para ver o que aconteceu antes da falha. No entanto, faltarão informações do Rundown (isso acontece no final de um rastreamento) para que as pilhas possam não ser resolvidas (dependendo de quais provedores foram ativados). Abra o rastreamento executando PerfView com o sinalizador /ContinueOnError na linha de comando. Os logs também conterão o local em que a exceção foi disparada.
  • Ao especificar um evento de interrupção por meio das opções --stopping-event-*, como o EventStream está sendo analisado de forma assíncrona, haverá alguns eventos passados entre o momento em que um evento de rastreamento correspondente às opções de evento de parada especificadas é analisado e o EventPipeSession é interrompido.

dotnet-trace convert

Converte rastreamentos nettrace em formatos alternativos para uso com ferramentas alternativas de análise de rastreamento.

Sinopse

dotnet-trace convert [<input-filename>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

Argumentos

  • <input-filename>

    Arquivo de rastreamento de entrada a ser convertido. O padrão é trace.nettrace.

Opções

  • --format <Chromium|NetTrace|Speedscope>

    Define o formato de saída para a conversão do arquivo de rastreamento.

  • -o|--output <output-filename>

    Nome do arquivo de saída. A extensão do formato de destino será adicionada.

Observação

Converter arquivos nettrace para chromium ou speedscope é irreversível. Arquivos speedscope e chromium não têm todas as informações necessárias para reconstruir arquivos nettrace. No entanto, o comando convert preserva o arquivo nettrace original, portanto, não exclua esse arquivo se você planeja abri-lo no futuro.

dotnet-trace ps

Lista os processos de dotnet dos quais os rastreamentos podem ser coletados. dotnet-trace 6.0.320703 e posteriores também exibem os argumentos de linha de comando com os quais cada processo foi iniciado, se disponível.

Observação

Para obter informações completas para processos enumerados de 64 bits, você precisa usar uma versão de 64 bits da dotnet-trace ferramenta.

Sinopse

dotnet-trace 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-trace ps. A saída que você verá é a seguinte. Os argumentos de linha de comando, se disponíveis, são mostrados no dotnet-trace versão 6.0.320703 e posterior.

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

dotnet-trace list-profiles

Lista perfis de rastreamento pré-criados com uma descrição de quais provedores e filtros estão em cada perfil.

Sinopse

dotnet-trace list-profiles [-h|--help]

dotnet-trace report

Cria um relatório em stdout de um rastreamento gerado anteriormente.

Sinopse

dotnet-trace report [-h|--help] <tracefile> [command]

Argumentos

  • <tracefile>

    O caminho do arquivo para o rastreamento que está sendo analisado.

Comandos

dotnet-trace report topN

Localiza os principais métodos N que estão na pilha de chamadas há mais tempo.

Sinopse
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
Opções
  • -n|--number <n>

Fornece os métodos N superiores na pilha de chamadas.

  • --inclusive

Produza os principais métodos N com base no tempo inclusivo . Se não for especificado, o tempo exclusivo será usado por padrão.

  • -v|--verbose

Produza os parâmetros de cada método na íntegra. Se não for especificado, os parâmetros serão truncados.

Coletar um rastreamento com dotnet-trace

Para coletar rastreamentos usando dotnet-trace:

  • Obtenha o PID (identificador de processo) do aplicativo .NET Core do qual os rastreamentos serão coletados.

    • No Windows, você pode usar o Gerenciador de Tarefas ou o comando tasklist, por exemplo.
    • No Linux, por exemplo, o comando ps.
    • dotnet-trace ps

  • Execute o comando a seguir:

    dotnet-trace collect --process-id <PID>

    O comando anterior gera uma saída semelhante à seguinte:

    Press <Enter> to exit...
Connecting to process: <Full-Path-To-Process-Being-Profiled>/dotnet.exe
Collecting to file: <Full-Path-To-Trace>/trace.nettrace
Session Id: <SessionId>
Recording trace 721.025 (KB)

  • Pare a coleção pressionando a tecla <Enter>. dotnet-trace concluirá eventos de log no arquivo trace.nettrace .

Iniciar um aplicativo filho e coletar um rastreamento de sua inicialização usando o dotnet-trace

Às vezes, pode ser útil coletar o rastreamento de um processo desde a inicialização. Para aplicativos que executam o .NET 5 ou posterior, é possível fazer isso usando o dotnet-trace.

Isso iniciará hello.exe com arg1 e arg2 como seus argumentos de linha de comando e coletará um rastreamento de sua inicialização de runtime:

dotnet-trace collect -- hello.exe arg1 arg2

O comando anterior gera uma saída semelhante à seguinte:

No profile or providers specified, defaulting to trace profile 'cpu-sampling'

Provider Name                           Keywords            Level               Enabled By
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile
Microsoft-Windows-DotNETRuntime         0x00000014C14FCCBD  Informational(4)    --profile

Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
Output File    : E:\temp\gcperfsim\trace.nettrace


[00:00:00:05]   Recording trace 122.244  (KB)
Press <Enter> or <Ctrl+C> to exit...

Você pode parar de coletar o rastreamento pressionando a tecla <Enter> ou <Ctrl + C>. Fazer isso também sairá hello.exe.

Observação

Inicializar hello.exepor meio de dotnet-trace redirecionará sua entrada/saída e você não poderá interagir com ele no console por padrão. Use a opção --show-child-io para interagir com stdin/stdout. Sair da ferramenta por meio de CTRL+C ou SIGTERM encerrará com segurança a ferramenta e o processo filho. Se o processo filho for encerrado antes da ferramenta, a ferramenta também será encerrada e o rastreamento será exibido com segurança.

Usar a porta de diagnóstico para coletar um rastreamento da inicialização do aplicativo

A porta de diagnóstico é um recurso de runtime adicionado ao .NET 5 que permite iniciar o rastreamento da inicialização do aplicativo. Para fazer isso usando dotnet-trace, você pode usar dotnet-trace collect -- <command> conforme descrito nos exemplos acima ou usar a opção --diagnostic-port.

Usar dotnet-trace <collect|monitor> -- <command> para iniciar o aplicativo como um processo filho é a maneira mais simples rastreá-lo rapidamente de sua inicialização.

No entanto, quando você quiser obter um controle mais fino sobre o tempo de vida do aplicativo que está sendo rastreado (por exemplo, monitore o aplicativo somente nos primeiros 10 minutos e continue executando) ou se você precisar interagir com o aplicativo usando a CLI, o uso da opção --diagnostic-port permite controlar o aplicativo de destino que está sendo monitorado e dotnet-trace.

  1. O comando a seguir faz com que dotnet-trace crie um soquete de diagnóstico chamado myport.sock e aguarde uma conexão.

    dotnet-trace collect --diagnostic-port myport.sock

    Saída:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=/home/user/myport.sock

  2. Em um console separado, inicie o aplicativo de destino com a variável de ambiente DOTNET_DiagnosticPorts definida como o valor na saída dotnet-trace.

    export DOTNET_DiagnosticPorts=/home/user/myport.sock
./my-dotnet-app arg1 arg2

    Em seguida, isso deve habilitar dotnet-trace para iniciar o rastreamento my-dotnet-app:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=myport.sock
Starting a counter session. Press Q to quit.

    Importante

    Iniciar seu aplicativo com dotnet run pode ser problemático porque a CLI dotnet pode gerar muitos processos filho que não são seu aplicativo e eles podem se conectar a dotnet-trace antes do seu aplicativo, deixando seu aplicativo para ser suspenso em tempo de execução. É recomendável que você use diretamente uma versão independente do aplicativo ou use dotnet exec para iniciar o aplicativo.

Exibir o rastreamento capturado do dotnet-trace

No Windows, você pode exibir arquivos .nettrace no Visual Studio ou No PerfView para análise.

No Linux, você pode exibir o rastreamento alterando o formato de saída de dotnet-trace para speedscope. Altere o formato do arquivo de saída usando a opção -f|--format. Você pode escolher entre nettrace (a opção padrão) e speedscope. A opção -f speedscope fará dotnet-trace produzir um arquivo speedscope. Arquivos Speedscope podem ser abertos em https://www.speedscope.app.

Para rastreamentos coletados em plataformas que não sejam Windows, você também pode mover o arquivo de rastreamento para um computador Windows e exibi-lo no Visual Studio ou No PerfView.

Observação

O runtime do .NET Core gera rastreamentos no formato nettrace. Os rastreamentos são convertidos em speedscope (se especificado) após a conclusão do rastreamento. Como algumas conversões podem resultar em perda de dados, o arquivo original nettrace é preservado ao lado do arquivo convertido.

Use o arquivo .rsp para evitar digitar comandos longos

Você pode iniciar dotnet-trace com um arquivo .rsp que contém os argumentos a serem passados. Isso pode ser útil ao habilitar provedores que esperam argumentos longos ou ao usar um ambiente shell que remove caracteres.

Por exemplo, o provedor a seguir pode ser complicado de digitar sempre que você quiser rastrear:

dotnet-trace collect --providers Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Além disso, o exemplo anterior contém " como parte do argumento. Como as aspas não são tratadas igualmente por cada shell, você pode enfrentar vários problemas ao usar shells diferentes. Por exemplo, o comando a ser inserido zsh é diferente do comando em cmd.

Em vez de digitar todas as vezes, você pode salvar o texto a seguir em um arquivo chamado myprofile.rsp.

--providers
Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Depois de salvar myprofile.rsp, você pode iniciar dotnet-trace com essa configuração usando o seguinte comando:

dotnet-trace @myprofile.rsp

Confira também