Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 em tempo de execução - por exemplo, o compilador Just-In-Time ou o coletor de lixo - e eventos escritos a partir de instâncias de EventSource nas bibliotecas e no código de utilizador.
Os eventos são então serializados no .nettrace formato de ficheiro e podem ser gravados diretamente num ficheiro ou transmitidos através de uma porta de diagnóstico para consumo em processo separado.
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 do runtime, o seu escopo é limitado ao código gerido e ao próprio runtime. Sem outras ferramentas de rastreamento, os eventos EventPipe incluem apenas rastros de pilha com informação de quadros de código gerido. Para obter eventos de outras bibliotecas de modo utilizador não geridas, amostragem de CPU para código nativo ou eventos do kernel, utilize ferramentas de rastreamento específicas do sistema operativo, como ETW ou perf_events. No Linux, a ferramenta perfcollect ajuda a automatizar o uso de perf_events e LTTng.
A partir do .NET 10, o EventPipe no Linux pode emitir eventos como user_events, permitindo a recolha de eventos geridos, eventos do sistema operativo/kernel e pilhas de chamadas nativas num único rastreio unificado. Este modo requer privilégios de administrador/root e kernel Linux 6.4+. Para obter mais informações, veja dotnet-trace collect-linux.
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 padrão, pode rastrear aplicações desde que o rastreador (por exemplo, dotnet-trace) seja executado com o mesmo utilizador que o utilizador que lançou a aplicação. O modo EventPipe (user_events) descrito anteriormente requer privilégios de administrador/root porque interage com a infraestrutura de rastreamento ao nível do sistema operativo.
A tabela a seguir é um resumo das diferenças entre EventPipe e ETW/perf_events.
| Caraterística | EventPipe | EventPipe (user_events) | ETW | perf_events (eventos de desempenho) |
|---|---|---|---|---|
| Multiplataforma | Sim | Não (apenas em distribuições Linux suportadas) | Não (apenas no Windows) | Não (apenas em distribuições Linux suportadas) |
| Exigir privilégio admin/root | Não | Sim | Sim | Sim |
| Pode obter eventos do SO/núcleo | Não | Sim | Sim | Sim |
| Pode resolver pilhas de chamadas nativas | Não | Sim | Sim | Sim |
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
Você também pode analisar rastreamentos EventPipe programaticamente com TraceEvent.
Ferramentas que usam 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 para1iniciar 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 viaDOTNET_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}emDOTNET_EventPipeOutputPathsã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 viaDOTNET_EnableEventPipe. O tamanho padrão do buffer é 1024MB, o que se traduz em essa variável de ambiente sendo definida como400, 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 para1habilitar a captura de números de processador em cabeçalhos de eventos do EventPipe. O valor predefinido é0.DOTNET_EventPipeConfig: Define a configuração da sessão do EventPipe ao iniciar uma sessão do EventPipe comDOTNET_EnableEventPipe. 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:5Microsoft-Windows-DotNETRuntimePrivate:4002000b:5Microsoft-DotNETCore-SampleProfiler:0:5
Para saber mais sobre alguns dos provedores conhecidos no .NET, consulte Provedores de eventos conhecidos.
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
