Partilhar via

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

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

Instalar

Há duas maneiras de baixar e instalar 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:

    Faça o download do executável da ferramenta que corresponde à sua plataforma:

    SO Plataforma
    Mac OS
    Aplicações Linux x64 | Braço | Arm64 | musl-x64 | musl-Arm64

Sinopse

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

Descrição

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.

  • Suporta duas formas diferentes de recolher vestígios:

    • O collect verbo oferece funcionalidade consistente em qualquer sistema operativo.
    • O collect-linux verbo utiliza capacidades específicas do sistema operativo Linux para fornecer funcionalidades adicionais.
    Característica collect collect-linux
    SO suportado Qualquer Apenas Linux, versão >do kernel = 6.4
    Requer privilégio de administrador/root Não Yes
    Rastreie todos os processos simultaneamente Não Suportado
    Capturar eventos nativos de biblioteca e kernel Não Suportado
    Os stacks de chamadas de eventos incluem frames 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 dotnet-trace
dotnet-trace collect-linux
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>]
    [--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. 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. Esta opção só se aplica quando --clrevents é especificada e não é sobreposta por --profile ou --providers. 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. Se o fornecedor Microsoft-Windows-DotNETRuntime de runtime CLR também estiver ativado através de --providers ou --profile, esta opção é ignorada. A tabela seguinte mostra a lista de palavras-chave disponíveis:

    Alias-chave de cadeia de palavras-chave Valor hexadecimal de palavras-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

    Pode ler sobre o fornecedor CLR com mais detalhe na documentação de referência do fornecedor de runtime .NET.

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

    Inicia dotnet-dsrouter e se conecta a ele. Requer dotnet-dsrouter para ser instalado. Corra 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. A predefinição é NetTrace.

  • -n, --name <name>

    O nome do processo do qual coletar o rastreamento.

    Nota

    No Linux e 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 atingirá o tempo limite.

  • --diagnostic-port <port-address[,(listen|connect)]>

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

    O port-address difere por SO:

    • 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 - uma porta IP:, como 127.0.0.1:9000.

    Por padrão, dotnet-trace ouve no endereço especificado. Em vez disso, você pode solicitar dotnet-trace a conexão anexando ,connect após o endereço. Por exemplo, --diagnostic-port /foo/tool1.socket,connect se conectará a um processo de tempo de execução .NET que está ouvindo o soquete de /foo/tool1.socket domínio Unix.

    Para saber como usar essa opção para coletar um rastreamento da inicialização do aplicativo, consulte Usar 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 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á <appname>_<yyyyMMdd>_<HHmmss>.nettrace, por exemplo, 'myapp_20210315_111514.nettrace''.

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

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

    Nota

    No Linux e 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 atingirá o tempo limite.

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

    Um perfil é um conjunto pré-definido de configurações de fornecedores para cenários comuns de rastreio. Múltiplos perfis podem ser especificados ao mesmo tempo, delimitados por vírgulas. Os fornecedores configurados por --providers sobreposição da configuração do perfil. De forma semelhante, se algum perfil configurar o fornecedor de tempo de execução CLR, irá sobrepor quaisquer configurações prescritas através --clreventsde .

    Quando --profile, , e --providers todos forem omitidos, --clrevents ativa perfis dotnet-trace collect e dotnet-commondotnet-sampled-thread-timepor defeito.

    Perfis disponíveis:

    Perfil Descrição
    dotnet-common Diagnósticos de execução .NET leves desenhados para manter baixa sobrecarga.
    Inclui GC, AssemblyLoader, Loader, JIT, Exceções, Threading, JittedMethodILToNativeMap e eventos de compilação
    Equivalente a --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Amostra pilhas de threads .NET (~100 Hz) para identificar hotspots ao longo do tempo. Utiliza o perfilador de amostras em tempo de execução com stacks geridos.
    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.
    database Captura comandos de base de dados ADO.NET e Entity Framework.

    Nota

    Em versões anteriores da ferramenta dotnet-trace, o verbo collect suportava um perfil chamado cpu-sampling. Este perfil foi removido porque o nome era enganador. Amostrava todas as threads independentemente do uso da CPU. Pode obter um resultado semelhante agora usando --profile dotnet-sampled-thread-time,dotnet-common. Se precisares de corresponder exatamente ao comportamento anterior cpu-sampling , usa --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 a serem habilitados EventPipe . Estes fornecedores complementam quaisquer fornecedores implícitos na --profile <list-of-comma-separated-profile-names>. Se houver qualquer inconsistência para um determinado fornecedor, esta configuração tem precedência sobre a configuração implícita de --profile e --clrevents.

    Esta lista de prestadores está na 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 interromper o rastreamento ao atingir o primeiro evento emitido pelo provedor de Microsoft-Windows-DotNETRuntime eventos.

  • --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 interromper o rastreamento ao atingir o primeiro Method/JittingStarted evento emitido pelo provedor de Microsoft-Windows-DotNETRuntime eventos.

  • --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 interromper 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.
  • 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.

dotnet-trace collect-linux

Nota

O collect-linux verbo é uma nova funcionalidade de pré-visualização e baseia-se numa versão atualizada do formato de ficheiro .nettrace. A versão mais recente do PerfView suporta estes ficheiros de rastreamento, mas outras formas de usar o ficheiro de rastreamento, como convert e report, podem ainda não funcionar.

Recolhe traços de diagnóstico usando perf_events, uma tecnologia de sistema operativo Linux. collect-linux permite as seguintes funcionalidades adicionais sobre collect.

Característica collect collect-linux
SO suportado Qualquer Apenas Linux, versão >do kernel = 6.4
Requer privilégio de Administrador/Root Não Yes
Rastreie todos os processos simultaneamente Não Suportado
Capturar eventos nativos de biblioteca e kernel Não Suportado
Os stacks de chamadas de eventos incluem frames nativos Não Yes

Pré-requisitos

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

Nota

O collect-linux verbo só funciona em ambientes linux x64 e linux arm64 que tenham glibc versão 2.35 ou superior. Todas as distribuições .NET 10 suportavam oficialmente este requisito , exceto Alpine 3.22, CentOS Stream 9 e quaisquer distribuições baseadas no Red Hat Enterprise Linux 9. Uma forma rápida de verificar a versão do libc de um sistema é com o comando ldd --version ou executando diretamente a biblioteca libc.

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, --profile, --clrevents, e --perf-events não são especificados, collect-linux ativa estes perfis por defeito:

  • dotnet-common — diagnósticos de execução .NET leves.
  • cpu-sampling — amostragem de CPU no kernel.

Por defeito, todos os processos na máquina são rastreados. Para traçar apenas um processo, use -n, --name <name> ou -p|--process-id <PID>.

Opções

Opções de Especificação do Provedor/Evento

  • --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 <list-of-comma-separated-profile-names>. Se houver qualquer inconsistência para um determinado fornecedor, esta configuração tem precedência sobre a configuração implícita de --profile e --clrevents.

    Esta lista de prestadores está na 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 fornecedores mais conhecidos em .NET, consulte Provedores de Eventos Conhecidos.

  • --clreventlevel <clreventlevel>

    Verbosidade dos eventos CLR a serem emitidos. Esta opção só se aplica quando --clrevents é especificada e não é sobreposta por --profile ou --providers. 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-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 fornecedor Microsoft-Windows-DotNETRuntime de runtime CLR também estiver ativado através de --providers ou --profile, esta opção é ignorada. A tabela seguinte mostra a lista de palavras-chave disponíveis:

    Alias-chave de cadeia de palavras-chave Valor hexadecimal de palavras-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

    Pode ler sobre o fornecedor CLR com mais detalhe na documentação de referência do fornecedor de runtime .NET.

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

    Uma lista separada por vírgulas de eventos de performance para incluir no rastreio. Os eventos disponíveis podem ser encontrados em tracefs, que normalmente é montado em /sys/kernel/tracing, até available_events para todos os eventos disponíveis ou através 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>

    Um perfil é um conjunto pré-definido de configurações de fornecedores para cenários comuns de rastreio. Múltiplos perfis podem ser especificados ao mesmo tempo, delimitados por vírgulas. Os fornecedores configurados por --providers sobreposição da configuração do perfil. De forma semelhante, se algum perfil configurar o fornecedor de tempo de execução CLR, irá sobrepor quaisquer configurações prescritas através --clreventsde .

    Quando --profile, --providers, --clrevents, e --perf-events são todos omitidos, dotnet-trace collect-linux ativa perfis dotnet-common e cpu-sampling por defeito.

    Perfis disponíveis:

    Perfil Descrição
    dotnet-common Diagnósticos de execução .NET leves desenhados para manter baixa sobrecarga.
    Inclui GC, AssemblyLoader, Loader, JIT, Exceções, Threading, JittedMethodILToNativeMap e eventos de compilação
    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 à CPU.
    thread-time Comutações de contexto do kernel thread, emitidas como Universal.Events/cswitch, para análise da CPU ligada/desligada e do escalonador.
    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.
    database Captura comandos de base de dados ADO.NET e Entity Framework.

Opções de Recolha de Vestígios

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

    O caminho de saída para os dados de rastreamento coletados. Se não especificado, por defeito é trace_<yyyyMMdd>_<HHmmss>.nettrace para o traço padrão de toda a máquina e para <appname>_<yyyyMMdd>_<HHmmss>.nettrace para um traço específico do processo (--name ou --process-id)

  • --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.

Opções de Destino de Processos .NET

Ver Comportamento da coleção padrão

  • -n, --name <name>

    O nome do processo do qual coletar o rastreamento.

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

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

Opções do modo sonda

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

    Probe os processos .NET para suporte ao comando IPC EventPipe UserEvents usado pelo collect-linux, sem recolher rasto. Os resultados listam primeiro os processos suportados. Use '-o stdout' para imprimir CSV (pid,processName,supportsCollectLinux) na consola, ou '-o output-filename' para escrever o CSV. Sonde um único processo com -n|--nome ou -p|--processo-id.

    Como correr collect-linux em modo de sonda não recolhe um rasto, não requer permissões root para ser executado. Não fornece validação dos pré-requisitos, e os processos .NET a correr em versões pré-visualizadas do .NET Runtime '10.0.0' são considerados não suportados.

Nota

Para recolher um rastreio usando dotnet-trace collect-linux, é necessário executá-lo com permissões root (CAP_PERFMON/CAP_SYS_ADMIN). Caso contrário, a ferramenta falhará em recolher eventos.

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

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

    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.

  • Interrompa a recolha pressionando a tecla Enter . dotnet-trace Vai terminar de registar eventos no .nettrace ficheiro.

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 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 <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 a sua aplicação dotnet run pode ser problemático porque a CLI dotnet pode gerar muitos processos filhos que não são a sua aplicação e que podem ligar-se dotnet-trace antes da sua aplicação, deixando a sua aplicação suspensa 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.

(Só para Linux) Recolha um traço para toda a máquina usando dotnet-trace

Este exemplo recolhe amostras de CPU para todos os processos na máquina. Quaisquer processos que executem .NET 10+ incluirão também alguns eventos leves adicionais que descrevem o comportamento de carregamento 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 múltiplas versões .NET instaladas, correr collect-linux em modo probe ajuda a discernir se um processo .NET pode ser rastreado com o 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 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

  • Last updated on