EventPipe

EventPipe é um componente de tempo de execução que pode ser usado para coletar dados de rastreamento, semelhante ao ETW ou perf_events. O objetivo do EventPipe é permitir que os desenvolvedores .NET rastreiem facilmente seus aplicativos .NET sem ter que depender de componentes de alto privilégio específicos da plataforma, como ETW ou perf_events.

EventPipe é o mecanismo por trás de muitas das ferramentas de diagnóstico e pode ser usado para consumir eventos emitidos pelo tempo de execução, bem como eventos personalizados escritos com EventSource.

Este artigo é uma visão geral de alto nível do EventPipe. Ele descreve quando e como usar o EventPipe e como configurá-lo para melhor atender às suas necessidades.

Noções básicas do EventPipe

O EventPipe agrega eventos emitidos por componentes de tempo de execução - por exemplo, o compilador Just-In-Time ou o coletor de lixo - e eventos escritos a partir de instâncias EventSource nas bibliotecas e no código do usuário.

Os eventos são então serializados no formato de arquivo e podem ser gravados diretamente em .nettrace um arquivo ou transmitidos através de uma porta de diagnóstico para consumo fora do processo.

Para saber mais sobre o formato NetTrace, consulte a documentação do formato NetTrace.

EventPipe vs ETW/perf_events

O EventPipe faz parte do tempo de execução do .NET e foi projetado para funcionar da mesma maneira em todas as plataformas suportadas pelo .NET Core. Isso permite que as ferramentas de rastreamento baseadas no EventPipe, como dotnet-counters, dotnet-gcdumpe dotnet-trace, funcionem perfeitamente entre plataformas.

No entanto, como o EventPipe é um componente interno de tempo de execução, seu escopo é limitado ao código gerenciado e ao próprio tempo de execução. Os eventos do EventPipe incluem stacktraces apenas com informações de quadro de código gerenciado. Se desejar eventos gerados a partir de outras bibliotecas de modo de usuário não gerenciadas, amostragem de CPU para código nativo ou eventos do kernel, use ferramentas de rastreamento específicas do sistema operacional, como ETW ou perf_events. No Linux, a ferramenta perfcollect ajuda a automatizar usando perf_events e LTTng.

Outra grande diferença entre o EventPipe e o ETW/perf_events é o requisito de privilégio admin/root. Para rastrear um aplicativo usando ETW ou perf_events você precisa ser um admin/root. Usando o EventPipe, você pode rastrear aplicativos desde que o rastreador (por exemplo, dotnet-trace) seja executado como o mesmo usuário que o usuário que iniciou o aplicativo.

A tabela a seguir é um resumo das diferenças entre EventPipe e ETW/perf_events.

Use o EventPipe para rastrear seu aplicativo .NET

Você pode usar o EventPipe para rastrear seu aplicativo .NET de várias maneiras:

• Use uma das ferramentas de diagnóstico criadas sobre o EventPipe.

• Use a biblioteca Microsoft.Diagnostics.NETCore.Client para escrever sua própria ferramenta para configurar e iniciar sessões do EventPipe.

• Use variáveis de ambiente para iniciar o EventPipe.

Depois de produzir um nettrace arquivo que contém seus eventos EventPipe, você pode exibir o arquivo em PerfView ou Visual Studio. Em plataformas que não sejam Windows, você pode converter o arquivo para um nettrace formato de rastreamento usando speedscope o Chromium comando dotnet-trace convert e visualizá-lo com speedscope ou Chrome DevTools.

Você também pode analisar rastreamentos EventPipe programaticamente com TraceEvent.

Ferramentas que usam o EventPipe

Essa é a maneira mais fácil de usar o EventPipe para rastrear seu aplicativo. Para saber mais sobre como usar cada uma dessas ferramentas, consulte a documentação de cada ferramenta.

• dotnet-counters permite monitorar e coletar várias métricas emitidas pelo tempo de execução do .NET e bibliotecas principais, bem como métricas personalizadas que você pode escrever.

• dotnet-gcdump permite coletar despejos de pilha GC de processos em tempo real para analisar o heap gerenciado de um aplicativo.

• dotnet-trace permite coletar rastreamentos de aplicativos para analisar o desempenho.

Rastrear usando variáveis de ambiente

O mecanismo preferencial para usar o EventPipe é usar dotnet-trace ou a biblioteca Microsoft.Diagnostics.NETCore.Client .

No entanto, você pode usar as seguintes variáveis de ambiente para configurar uma sessão do EventPipe em um aplicativo e fazer com que ele grave o rastreamento diretamente em um arquivo. Para interromper o rastreamento, saia do aplicativo.

• DOTNET_EnableEventPipe: Defina isso para 1 iniciar uma sessão do EventPipe que grava diretamente em um arquivo. O valor predefinido é 0.

• DOTNET_EventPipeOutputPath: O caminho para o arquivo de rastreamento EventPipe de saída quando ele está configurado para ser executado via DOTNET_EnableEventPipe. O valor padrão é trace.nettrace, que será criado no mesmo diretório a partir do qual o aplicativo está sendo executado.

  Nota

  Desde o .NET 6, instâncias da cadeia de caracteres {pid} em DOTNET_EventPipeOutputPath são substituídas pela id do processo que está sendo rastreado.

• DOTNET_EventPipeCircularMB: Um valor hexadecimal que representa o tamanho do buffer interno do EventPipe em megabytes. Esse valor de configuração só é usado quando o EventPipe está configurado para ser executado via DOTNET_EnableEventPipe. O tamanho padrão do buffer é 1024MB, o que se traduz em essa variável de ambiente sendo definida como 400, desde0x400 == 1024 .

  Nota

  Se o processo de destino gravar eventos com muita frequência, ele poderá estourar esse buffer e alguns eventos poderão ser descartados. Se muitos eventos estiverem sendo descartados, aumente o tamanho do buffer para ver se o número de eventos descartados diminui. Se o número de eventos descartados não diminuir com um tamanho de buffer maior, isso pode ser devido a um leitor lento impedindo que os buffers do processo de destino sejam liberados.

• DOTNET_EventPipeProcNumbers: Defina isso para 1 habilitar a captura de números de processador em cabeçalhos de eventos do EventPipe. O valor predefinido é 0.

• DOTNET_EventPipeConfig: Configura a configuração da sessão do EventPipe ao iniciar uma sessão do EventPipe com DOTNET_EnableEventPipeo . A sintaxe é a seguinte:

  <provider>:<keyword>:<level>

  Você também pode especificar vários provedores concatenando-os com uma vírgula:

  <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

  Se essa variável de ambiente não estiver definida, mas o EventPipe estiver habilitado pelo DOTNET_EnableEventPipe, ele começará a rastrear habilitando os seguintes provedores com as seguintes palavras-chave e níveis:

  • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
  • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
  • Microsoft-DotNETCore-SampleProfiler:0:5

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