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

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

Instalar

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

Ferramenta global dotnet:

Para instalar a versão mais recente do dotnet-tracepacote NuGet, use o comando dotnet tool install:
```
dotnet tool install --global dotnet-trace
```
Download direto:

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

Sistema operacional Plataforma

Windows x86 | x64 | Braço | Arm-x64

Linux x64 | Braço | Arm64 | musl-x64 | musl-Arm64

Sistema operacional	Plataforma
Windows	x86 \| x64 \| Braço \| Arm-x64
Linux	x64 \| Braço \| Arm64 \| musl-x64 \| musl-Arm64

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.

Dá suporte a duas maneiras diferentes de coletar rastreamentos:

O collect verbo oferece funcionalidade consistente em qualquer sistema operacional.
O collect-linux verbo usa recursos de sistema operacional específicos do Linux para fornecer recursos adicionais.

Característica	`collect`	`collect-linux`
Sistema operacional com suporte	Qualquer	Somente Linux, versão >do kernel = 6.4
Requer privilégio de administrador/raiz	Não	Yes
Rastrear todos os processos simultaneamente	Não	Suportado
Capturar eventos de kernel e biblioteca nativa	Não	Suportado
As chamadas de evento incluem quadros nativos	Não	Yes

Opções

-h|--help

Mostra a ajuda da linha de comando.
--version

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

Comandos

Comando
coleta de rastreamento de dotnet
dotnet-trace collect-linux
conversão dotnet-trace
dotnet-trace ps
dotnet-trace list-profiles
relatório dotnet-trace

coleta de rastreamento de dotnet

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>]
    [--dsrouter <ios|ios-sim|android|android-emu>]
    [--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 <list-of-comma-separated-profile-names>]
    [--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. Essa opção só se aplica quando --clrevents é especificada e não substituída por --profile ou --providers. 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

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. Se o provedor Microsoft-Windows-DotNETRuntime de runtime CLR também estiver habilitado por meio --providers ou --profile, essa opção será ignorada. A tabela a seguir mostra a lista de palavras-chave disponíveis:

Alias de cadeia de caracteres de palavra-chave	Valor hex da palavra-chave
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`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`
`managedheapcollect`	`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`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

Você pode ler sobre o provedor CLR com mais detalhes sobre a documentação de referência do provedor de runtime do .NET.

'--dsrouter {ios|ios-sim|android|android-emu}

Inicia o dotnet-dsrouter e conecta-se a ele. Requer que o dotnet-dsrouter seja instalado. Execute dotnet-dsrouter -h para obter mais informações.
--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.

Observação

No Linux e no macOS, usar essa opção requer o aplicativo de destino e dotnet-trace compartilhar a mesma TMPDIR variável de ambiente. Caso contrário, o comando terá um tempo limite.
--diagnostic-port <port-address[,(listen|connect)]>

Define a porta de diagnóstico usada para se comunicar com o processo a ser rastreado. o dotnet-trace e o runtime do .NET dentro do processo de destino devem concordar com o endereço da porta, com um escutando e o outro se conectando. O dotnet-trace determina automaticamente a porta correta ao anexar usando as --process-id opções ou --name ao iniciar um processo usando a opção -- <command> . Geralmente, só é necessário especificar a porta explicitamente ao aguardar um processo que será iniciado no futuro ou se comunicar com um processo em execução dentro de um contêiner que não faz parte do namespace do processo atual.

As port-address diferenças por sistema operacional:
- Linux e macOS – um caminho para um soquete de domínio unix, como /foo/tool1.socket.
- Windows – um caminho para um pipe nomeado, como \\.\pipe\my_diag_port1.
- Android, iOS e tvOS – um IP:port como 127.0.0.1:9000.
Por padrão, dotnet-trace escuta no endereço especificado. Em vez disso, você pode solicitar dotnet-trace a conexão acrescentando ,connect após o endereço. Por exemplo, --diagnostic-port /foo/tool1.socket,connect se conectará a um processo de runtime do .NET que está escutando o soquete de domínio unix /foo/tool1.socket .

Para saber como usar essa opção para coletar um rastreamento da inicialização do aplicativo, consulte Usar a porta de diagnóstico 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 <appname>_<yyyyMMdd>_<HHmmss>.nettraceserá , por exemplo, "myapp_20210315_111514.nettrace".
-p|--process-id <PID>

ID do processo do qual coletar o rastreamento.

Observação

No Linux e no macOS, usar essa opção requer o aplicativo de destino e dotnet-trace compartilhar a mesma TMPDIR variável de ambiente. Caso contrário, o comando terá um tempo limite.

--profile <list-of-comma-separated-profile-names>

Um perfil é um conjunto predefinido de configurações de provedor para cenários comuns de rastreamento. Vários perfis podem ser especificados por vez, delimitados por vírgulas. Provedores configurados por meio --providers da substituição da configuração do perfil. Da mesma forma, se qualquer perfil configurar o provedor de runtime CLR, ele substituirá todas as configurações prescritas por meio --clreventsde .

Quando --profile, --providerse --clrevents todos são omitidos, dotnet-trace collect habilita perfis dotnet-common e dotnet-sampled-thread-time por padrão.

Perfis disponíveis:

Perfil	Descrição
`dotnet-common`	Diagnóstico de runtime leve do .NET projetado para manter a sobrecarga baixa. Inclui eventos GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap e Compilation Equivalente a `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`.
`dotnet-sampled-thread-time`	Exemplos de pilhas de thread do .NET (aproximadamente 100 Hz) para identificar pontos de acesso ao longo do tempo. Usa o criador de perfil de exemplo de runtime com pilhas gerenciadas.
`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.
`database`	Captura comandos de banco de dados do ADO.NET e do Entity Framework.

Observação

Em versões anteriores da ferramenta dotnet-trace, o verbo de coleta tinha suporte para um perfil chamado cpu-sampling. Esse perfil foi removido porque o nome era enganoso. Ele exemplou todos os threads, independentemente do uso da CPU. Você pode obter um resultado semelhante agora usando --profile dotnet-sampled-thread-time,dotnet-common. Se você precisar corresponder exatamente ao comportamento anterior cpu-sampling , use --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

--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 <list-of-comma-separated-profile-names>. Se houver alguma inconsistência para um provedor específico, essa configuração terá precedência sobre a configuração implícita de --profile e --clrevents.

Esta lista de provedores está no formulário Provider[,Provider]:
- Provider está no formulário: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs está no formulário: [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. Desabilite o currículo do runtime usando --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 ao atingir o primeiro evento emitido pelo Microsoft-Windows-DotNETRuntime provedor de eventos.
--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 ao atingir o primeiro Method/JittingStarted evento emitido pelo Microsoft-Windows-DotNETRuntime provedor de eventos.
--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 Method/JittingStarted evento do método OnButtonClick no Program namespace emitido pelo Microsoft-Windows-DotNETRuntime provedor de eventos.

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.

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 collect-linux

Observação

O collect-linux verbo é um novo recurso de visualização e depende de uma versão atualizada do formato de arquivo .nettrace. A versão mais recente do PerfView dá suporte a esses arquivos de rastreamento, mas outras maneiras de usar o arquivo de rastreamento, como convert e report, talvez, ainda não funcionem.

Coleta rastreamentos de diagnóstico usando perf_events, uma tecnologia do sistema operacional Linux. collect-linuxhabilita os seguintes recursos adicionais.collect

Característica	`collect`	`collect-linux`
Sistema operacional com suporte	Qualquer	Somente Linux, versão >do kernel = 6.4
Requer privilégio de administrador/raiz	Não	Yes
Rastrear todos os processos simultaneamente	Não	Suportado
Capturar eventos de kernel e biblioteca nativa	Não	Suportado
As chamadas de evento incluem quadros nativos	Não	Yes

Pré-requisitos

Kernel do Linux com CONFIG_USER_EVENTS=y suporte (kernel 6.4+)
Permissões raiz
.NET 10+

Observação

O collect-linux verbo é executado apenas em ambientes linux x64 e linux arm64 que têm a versão glibc 2.35 ou superior. Todas as distribuições do Linux com suporte oficial do .NET 10 dão suporte a esse requisito, exceto Alpine 3.22, CentOS Stream 9 e quaisquer distribuições baseadas no Red Hat Enterprise Linux 9. Uma maneira rápida de verificar a versão do libc de um sistema é com o comando ldd --version ou executando a biblioteca libc diretamente.

Sinopse

dotnet-trace collect-linux
    [-h|--help]

    # Provider/Event Specification
    [--providers <list-of-comma-separated-providers>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--perf-events <list-of-perf-events>]
    [--profile <list-of-comma-separated-profile-names>]

    # Trace Collection
    [-o|--output <trace-file-path>]
    [--duration dd:hh:mm:ss]

    # .NET Process Target (Optional)
    [-n, --name <name>]
    [-p|--process-id <pid>]

    # Probe mode
    [--probe]

Comportamento padrão da coleção

Quando --providers, --profilee --clrevents--perf-events não são especificados, collect-linux habilita esses perfis por padrão:

dotnet-common — diagnóstico de runtime leve do .NET.
cpu-sampling — amostragem da CPU do kernel.

Por padrão, todos os processos no computador são rastreados. Para rastrear apenas um processo, use -n, --name <name> ou -p|--process-id <PID>.

Opções

Opções de especificação de provedor/evento

--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 <list-of-comma-separated-profile-names>. Se houver alguma inconsistência para um provedor específico, essa configuração terá precedência sobre a configuração implícita de --profile e --clrevents.

Esta lista de provedores está no formulário Provider[,Provider]:
- Provider está no formulário: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs está no formulário: [key1=value1][;key2=value2]
Para saber mais sobre alguns dos provedores conhecidos no .NET, consulte Provedores de Eventos conhecidos.
--clreventlevel <clreventlevel>

Verbosidade de eventos CLR a serem emitidos. Essa opção só se aplica quando --clrevents é especificada e não substituída por --profile ou --providers. 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

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-linux --providers Microsoft-Windows-DotNETRuntime:3:4 solicita o mesmo conjunto de eventos que dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Se o provedor Microsoft-Windows-DotNETRuntime de runtime CLR também estiver habilitado por meio --providers ou --profile, essa opção será ignorada. A tabela a seguir mostra a lista de palavras-chave disponíveis:

Alias de cadeia de caracteres de palavra-chave	Valor hex da palavra-chave
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`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`
`managedheapcollect`	`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`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

Você pode ler sobre o provedor CLR com mais detalhes sobre a documentação de referência do provedor de runtime do .NET.

--perf-events <list-of-perf-events>

Uma lista separada por vírgulas de eventos perf a serem incluídos no rastreamento. Eventos disponíveis podem ser encontrados em tracefs, que normalmente são montados em /sys/kernel/tracing, por meio available_events de todos os eventos disponíveis ou por meio do events/ subdiretório para eventos categorizados.

Exemplo: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

--profile <list-of-comma-separated-profile-names>

Quando --profile, --providerse --clrevents--perf-events todos são omitidos, dotnet-trace collect-linux habilita perfis dotnet-common e cpu-sampling por padrão.

Perfis disponíveis:

Perfil	Descrição
`dotnet-common`	Diagnóstico de runtime leve do .NET projetado para manter a sobrecarga baixa. Inclui eventos GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap e Compilation Equivalente a `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`.
`cpu-sampling`	Amostragem de CPU do kernel (baseada em perf), emitida como `Universal.Events/cpu`, para atribuição precisa na CPU.
`thread-time`	Comutadores de contexto de thread do kernel, emitidos como `Universal.Events/cswitch`, para análise ativa/off-CPU e agendador.
`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.
`database`	Captura comandos de banco de dados do ADO.NET e do Entity Framework.

Opções de coleção de rastreamento

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

O caminho de saída para os dados de rastreamento coletados. Se não for especificado, ele usará como padrão trace_<yyyyMMdd>_<HHmmss>.nettrace o rastreamento padrão em todo o computador e para <appname>_<yyyyMMdd>_<HHmmss>.nettrace um rastreamento específico do processo (--name ou --process-id)
--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.

Opções de destino do processo do .NET

Consulte o comportamento padrão da coleção

-n, --name <name>

O nome do processo do qual coletar o rastreamento.
-p|--process-id <PID>

ID do processo do qual coletar o rastreamento.

Opções de modo de investigação

--probe [-n|--name] [-p|--process-id] [-o|--output <stdout|output-filename>]

Investigue os processos do .NET para dar suporte ao comando IPC EventPipe UserEvents usado pelo collect-linux, sem coletar um rastreamento. Primeiro, os processos compatíveis com a lista de resultados. Use '-o stdout' para imprimir CSV (pid, processName, supportsCollectLinux) no console ou '-o output-filename' para gravar o CSV. Investigue um único processo com -n|--name ou -p|--process-id.

Como a execução collect-linux no modo de investigação não coleta um rastreamento, ela não requer permissões raiz para execução. Ele não fornece a validação dos pré-requisitos e os processos do .NET em execução nas versões prévias do Runtime do .NET '10.0.0' são considerados sem suporte.

Observação

Para coletar um rastreamento usandodotnet-trace collect-linux, ele precisa ser executado com permissões raiz (CAP_PERFMON/CAP_SYS_ADMIN). Caso contrário, a ferramenta falhará ao coletar eventos.

conversão dotnet-trace

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]

relatório dotnet-trace

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

topN do relatório dotnet-trace

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 collect:

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:

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

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

Process        : <full-path-to-process-being-trace>
Output File    : <process>_20251007_154557.nettrace
[00:00:00:02]   Recording trace 178.172  (KB)
Press <Enter> or <Ctrl+C> to exit...
Stopping the trace. This may take several minutes depending on the application being traced.

Trace completed.

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

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 profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  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.

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

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 do dotnet pode gerar muitos processos filho que não são seu aplicativo e eles podem se conectar antes dotnet-trace do seu aplicativo, deixando seu aplicativo para ser suspenso em runtime. É recomendável que você use diretamente uma versão independente do aplicativo ou use dotnet exec para iniciar o aplicativo.

(Somente Linux) Coletar um rastreamento em todo o computador usando dotnet-trace

Este exemplo captura exemplos de CPU para todos os processos no computador. Todos os processos que executam o .NET 10+ também incluirão alguns eventos leves adicionais que descrevem o comportamento de carregamento de GC, JIT e Assembly.

$ sudo dotnet-trace collect-linux
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile

Linux Perf Events                                                               Enabled By
cpu-sampling                                                                    --profile

Output File    : <path-to-nettrace>trace_20251008_181939.nettrace

[00:00:00:03]   Recording trace.
Press <Enter> or <Ctrl-C> to exit...

Recording stopped.
Resolving symbols.
Finished recording trace.
Trace written to <path-to-nettrace>trace_20251008_181939.nettrace

Para ambientes com várias versões do .NET instaladas, a execução collect-linux no modo de investigação ajuda a discernir se um processo .NET é capaz de ser rastreado com collect-linux.

$ dotnet-trace collect-linux --probe
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

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

Provedores de eventos conhecidos do .NET

Comentários

Esta página foi útil?

Last updated on 2026-01-08

Compartilhar via

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

Instalar

Sinopse

Descrição

Opções

Comandos

coleta de rastreamento de dotnet

Sinopse

Opções

dotnet-trace collect-linux

Pré-requisitos

Sinopse

Comportamento padrão da coleção

Opções

Opções de especificação de provedor/evento

Opções de coleção de rastreamento

Opções de destino do processo do .NET

Opções de modo de investigação

conversão dotnet-trace

Sinopse

Argumentos

Opções

dotnet-trace ps

Sinopse

Exemplo

dotnet-trace list-profiles

Sinopse

relatório dotnet-trace

Sinopse

Argumentos

Comandos

topN do relatório dotnet-trace

Sinopse

Opções

Coletar um rastreamento com dotnet-trace

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

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

(Somente Linux) Coletar um rastreamento em todo o computador usando dotnet-trace

Exibir o rastreamento capturado do dotnet-trace

Use o arquivo .rsp para evitar digitar comandos longos

Confira também

Comentários

Recursos adicionais