Partilhar via

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

  • Artigo

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

Instalar

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

Sinopse

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

Description

A dotnet-trace ferramenta:

  • É uma ferramenta .NET Core multiplataforma.
  • Permite a coleta de rastreamentos do .NET Core de um processo em execução sem um criador de perfil nativo.
  • É baseado no EventPipe tempo de execução 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 para executar o rastreamento. --duration 00:00:00:05 irá executá-lo por 5 segundos.

Comandos

Comando
coleta dotnet-trace
conversão dotnet-trace
Dotnet-Trace PS
dotnet-trace list-perfis
Relatório dotnet-trace

coleta dotnet-trace

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

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. Padrão 256 MB.

    Nota

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

  • --clreventlevel <clreventlevel>

    Verbosidade dos eventos CLR a serem emitidos. A tabela a seguir mostra os níveis de evento 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 tempo de execução CLR para habilitar separadas por + sinais. Este é um mapeamento simples que permite especificar palavras-chave de eventos 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 sobre o provedor CLR mais detalhadamente na documentação de referência do provedor de tempo de execução do .NET.

  • --format {Chromium|NetTrace|Speedscope}

    Define o formato de saída para a conversão do arquivo de rastreamento. A predefiniçã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 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 dd:hh:mm:ss formato. Por exemplo 00:00:00:05 , irá executá-lo 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á , por <appname>_<yyyyMMdd>_<HHmmss>.nettraceexemplo, 'myapp_20210315_111514.nettrace''.

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

    A ID do processo a partir da qual coletar o rastreamento.

  • --profile <profile-name>

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

Perfil Description
cpu-sampling Útil para controlar o uso da CPU e informações gerais de tempo de execução do .NET. Esta é a opção padrão se nenhum perfil ou provedores forem especificados.
gc-verbose Rastreia coleções GC e alocações de objetos de amostras.
gc-collect Rastreia coleções de GC apenas com despesas gerais muito baixas.

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

    Uma lista separada por vírgulas de provedores a serem habilitados EventPipe . Estes fornecedores complementam quaisquer fornecedores implícitos na --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 fornecedores apresenta-se sob a forma:

    • Provider[,Provider]
    • Provider está na forma: KnownProviderName[:Flags[:Level][:KeyValueArgs]].
    • KeyValueArgs está na forma: [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 o .NET 5 ou posterior)

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

    Nota

    O uso dessa opção monitora o primeiro processo .NET que se comunica 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 autônomos ou usando a dotnet exec <app.dll> opção.

  • --show-child-io

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

  • --resume-runtime

    Retomar o tempo de execução depois que a sessão for inicializada, o padrão é true. Desative a retomada do tempo de execução usando --resume-runtime:false.

  • --stopping-event-provider-name

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

  • --stopping-event-event-name

    Uma cadeia de caracteres, analisada como está, que interromperá o rastreamento ao atingir um evento com o nome do evento correspondente. Requer --stopping-event-provider-name ser definido. Para um evento de paragem mais específico, forneça adicionalmente .--stopping-event-payload-filter por exemplo, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted para parar o rastreamento ao atingir o primeiro Method/JittingStarted evento emitido pelo provedor do Microsoft-Windows-DotNETRuntime evento.

  • --stopping-event-payload-filter

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

Nota

  • Parar o rastreamento pode levar muito tempo (até minutos) para aplicações grandes. O tempo de execução precisa enviar o cache de tipo para todo o código gerenciado que foi capturado no rastreamento.
  • No Linux e macOS, este comando espera que o aplicativo de destino e dotnet-trace compartilhe a mesma TMPDIR variável de ambiente. Caso contrário, o comando atingirá o tempo limite.
  • Para coletar um rastreamento usando dotnet-traceo , 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.
  • Se ocorrer uma exceção não tratada durante a execução dotnet-trace collect, isso resultará em um rastreamento incompleto. Se encontrar a causa raiz da exceção for sua prioridade, navegue até Coletar despejos em caso de falha. Como resultado da exceção não tratada, o rastreamento é truncado quando o tempo de execução é desligado para evitar outros comportamentos indesejados, como travamento ou corrupção de dados. Mesmo que o rastreamento esteja incompleto, você ainda pode abri-lo para ver o que aconteceu antes da falha. No entanto, faltarão informações de Rundown (isso acontece no final de um rastreamento), então as pilhas podem 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 acionada.
  • Ao especificar um evento de parada através das --stopping-event-* opções, como o EventStream está sendo analisado de forma assíncrona, haverá alguns eventos que passam entre o momento em que um evento de rastreamento correspondente às opções de evento de parada especificadas é analisado e o EventPipeSession é interrompido.

conversão dotnet-trace

Converte rastreamentos em formatos alternativos para uso com ferramentas alternativas nettrace 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. Será adicionada uma extensão do formato de destino.

Nota

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

Dotnet-Trace PS

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

Nota

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

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]

Relatório dotnet-trace

Cria um relatório no stdout a partir 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

relatório dotnet-trace 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 principais métodos N na pilha de chamadas.

  • --inclusive

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

  • -v|--verbose

Saída dos 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 recolher vestígios utilizando dotnet-trace:

  • Obtenha o identificador de processo (PID) do aplicativo .NET Core do qual coletar rastreamentos.

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

  • Execute o seguinte comando:

    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 coleta pressionando a <Enter> tecla . dotnet-trace concluirá o registro de eventos no arquivo trace.nettrace .

Inicie um aplicativo filho e colete um rastreamento de sua inicialização usando dotnet-trace

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

Isso será iniciado hello.exe com arg1 e arg2 como seus argumentos de linha de comando e coletará um rastreamento de sua inicialização em tempo de execução:

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 <Enter> ou <Ctrl + C> tecla . Fazer isso também vai sair hello.exe.

Nota

Iniciar hello.exe via dotnet-trace redirecionará sua entrada/saída e você não poderá interagir com ele no console por padrão. Use o --show-child-io interruptor para interagir com seu stdin/stdout. Sair da ferramenta via CTRL+C ou SIGTERM terminará com segurança a ferramenta e o processo filho. Se o processo filho sair antes da ferramenta, a ferramenta também sairá e o rastreamento deve ser visível 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 tempo de execução adicionado no .NET 5 que permite iniciar o rastreamento a partir da inicialização do aplicativo. Para fazer isso usando dotnet-traceo , você pode usar dotnet-trace collect -- <command> como descrito nos exemplos acima ou usar a --diagnostic-port opção.

Usar dotnet-trace <collect|monitor> -- <command> para iniciar o aplicativo como um processo filho é a maneira mais simples de rastrear rapidamente o aplicativo desde 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, monitorar o aplicativo apenas nos primeiros 10 minutos e continuar executando) ou se precisar interagir com o aplicativo usando a CLI, usar --diagnostic-port a opção permite controlar o aplicativo de destino que está sendo monitorado e dotnet-trace.

  1. O comando abaixo faz dotnet-trace criar um soquete de diagnóstico chamado myport.sock e aguardar 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 DOTNET_DiagnosticPorts de ambiente definida como o valor na dotnet-trace saída.

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

    Isto deverá permitir dotnet-trace iniciar o rastreio 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 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 PerfView para análise.

No Linux, você pode visualizar o rastreamento alterando o formato de saída de dotnet-trace para speedscope. Altere o formato do arquivo de saída usando a -f|--format opção. Você pode escolher entre nettrace (a opção padrão) e speedscope. A opção -f speedscope fará produzir dotnet-trace um speedscope arquivo. Speedscope Os ficheiros 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 uma máquina Windows e exibi-lo no Visual Studio ou PerfView.

Nota

O tempo de execução do nettrace .NET Core gera rastreamentos no formato. 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 .rsp arquivo que contém os argumentos a serem aprovados. Isso pode ser útil ao habilitar provedores que esperam argumentos longos ou ao usar um ambiente de shell que remove caracteres.

Por exemplo, o seguinte provedor pode ser complicado de digitar cada vez que você deseja 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 cotações 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 isso sempre, você pode salvar o seguinte texto 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.rspo , você pode iniciar dotnet-trace com essa configuração usando o seguinte comando:

dotnet-trace @myprofile.rsp

Consulte também