Partilhar via

EventPipe

  • Artigo

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

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 de serialização EventPipe, consulte a documentação do formato EventPipe.

EventPipe vs. ETW/LTTng

O EventPipe faz parte do tempo de execução do .NET (CoreCLR) 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. O EventPipe não pode ser usado para rastrear alguns eventos de nível inferior, como resolver a pilha de código nativo ou obter vários eventos do kernel. Se você usa interoperabilidade C/C++ em seu aplicativo ou deseja rastrear o tempo de execução em si (que é escrito em C++), ou deseja diagnósticos mais profundos sobre o comportamento do aplicativo que requer eventos do kernel (ou seja, eventos de comutação de contexto de thread nativo), você deve usar ETW ou perf/LTTng.

Outra grande diferença entre o EventPipe e o ETW/LTTng é o requisito de privilégio admin/root. Para rastrear um aplicativo usando ETW ou LTTng 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/LTTng.

Caraterística EventPipe ETW LTTng
Várias plataformas Sim Não (apenas no Windows) Não (apenas em distribuições Linux suportadas)
Exigir privilégio admin/root Não Sim Sim
Pode obter eventos do SO/kernel Não Sim Sim
Pode resolver pilhas de chamadas nativas Não Sim Sim

Use o EventPipe para rastrear seu aplicativo .NET

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

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 speedscope formato de rastreamento usando Chromium o nettrace 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, desde == 0x4001024 .

    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.

Nota

O .NET 6 padroniza o prefixo DOTNET_ em vez de variáveis de ambiente que configuram o comportamento em tempo de execução do COMPlus_ .NET. No entanto, o prefixo COMPlus_ continuará a funcionar. Se você estiver usando uma versão anterior do tempo de execução do .NET, ainda deverá usar o prefixo COMPlus_ para variáveis de ambiente.