Coletar e exibir rastreamentos EventSource

Artigo
05/09/2023

Este artigo se aplica a: ✔️ .NET Core 3.1 e versões posteriores ✔️ .NET Framework 4.5 e versões posteriores

O Guia de introdução mostrou como criar um EventSource mínimo e coletar eventos em um arquivo de rastreamento. Este tutorial mostra como as diferentes ferramentas podem configurar quais eventos são coletados em um rastreamento e, em seguida, exibir os rastreamentos.

Aplicativo de exemplo

Você usará o aplicativo de exemplo a seguir que gera eventos para este tutorial. Compile um aplicativo de console .NET que contém este código:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Configurar quais eventos coletar

A maioria das ferramentas de coleta de eventos usa estas opções de configuração para decidir quais eventos devem ser incluídos em um rastreamento:

Nomes de provedor: uma lista de um ou mais nomes EventSource. Somente os eventos definidos em EventSources nessa lista estão qualificados para inclusão. Para coletar eventos da classe DemoEventSource no aplicativo de exemplo anterior, você precisará incluir o nome de EventSource "Demonstração" na lista de nomes de provedor.
Nível de detalhes do evento: para cada provedor, você pode definir um nível de detalhamento, e os eventos com detalhamento mais alto que esse nível serão excluídos do rastreamento. Se você especificasse que o provedor "Demonstração" no aplicativo de exemplo anterior deve coletar no nível de detalhamento Informativo, o evento DebugMessage seria excluído porque ele tem um nível superior. A especificação de EventLevel LogAlways (0) é um caso especial que indica que os eventos de qualquer nível de detalhes devem ser incluídos.
Palavras-chave do evento: para cada provedor, você pode definir um conjunto de palavras-chave e somente os eventos marcados com pelo menos uma das palavras-chave serão incluídos. No aplicativo de exemplo acima, se você especificou a palavra-chave Startup, somente os eventos AppStarted e DebugMessage seriam incluídos. Se nenhuma palavra-chave for especificada, esse é um caso especial e significa que os eventos com qualquer palavra-chave devem ser incluídos.

Convenções para descrever a configuração do provedor

Embora cada ferramenta determine sua própria interface de usuário para definir a configuração de rastreamento, há uma convenção comum que muitas ferramentas usam ao especificar a configuração como uma cadeia de caracteres de texto. A lista de provedores é especificada como uma lista delimitada por ponto e vírgula, e cada elemento de provedor na lista consiste em nome, palavras-chave e níveis separados por dois-pontos. Por exemplo, "Demo:3:5" identifica o EventSource chamado “Demonstração” com a palavra-chave bitmask 3 (o bit Startup e o bit Requests) e EventLevel 5, que é Verbose. Muitas ferramentas também permitem omitir o nível e as palavras-chave se nenhuma filtragem de nível ou palavra-chave for desejada. Por exemplo, "Demo::5" apenas faz a filtragem baseada em nível, "Demo:3" apenas faz a filtragem baseada em palavra-chave e "Demo" não faz nenhuma filtragem de palavra-chave ou de nível.

Visual Studio

O criador de perfil do Visual Studio dá suporte à coleta e à exibição de rastreamentos. Ele também pode exibir rastreamentos que foram coletados antecipadamente por outras ferramentas, como dotnet-trace.

Coletar um rastreamento

A maioria das ferramentas de criação de perfil do Visual Studio usa conjuntos predefinidos de eventos que atendem a uma finalidade específica, como analisar o uso ou as alocações de CPU. Para coletar um rastreamento com eventos personalizados, você usará a ferramenta Visualizador de Eventos.

Para abrir o Criador de Perfil de Desempenho no Visual Studio, selecione Alt+F2.
Marque a caixa de seleção Visualizador de Eventos.
Selecione o ícone de engrenagem pequeno à direita do Visualizador de Eventos para abrir a janela de configuração.

Na tabela abaixo de Provedores Adicionais, adicione uma linha a cada provedor que você deseja configurar clicando na caixa de seleção Habilitado e, em seguida, insira o nome do provedor, as palavras-chave e o nível. Você não precisa inserir o GUID do provedor; ele é calculado automaticamente.
Selecione OK para confirmar as definições de configuração.
Selecione Iniciar para começar a executar o aplicativo e coletar logs.
Selecione Parar Coleta ou saia do aplicativo para parar de coletar logs e mostrar os dados coletados.

Exibir um rastreamento

O Visual Studio pode exibir os rastreamentos que ele coletou ou pode exibir rastreamentos coletados por outras ferramentas. Para exibir rastreamentos de outras ferramentas, use Arquivo>Abrir e selecione um arquivo de rastreamento no seletor de arquivos. O criador de perfil do Visual Studio dá suporte a arquivos .etl (formato padrão do ETW), .nettrace (formato padrão do EventPipe) e .diagsession (formato padrão do Visual Studio). Para saber mais sobre como trabalhar com arquivos de rastreamento no Visual Studio, confira a documentação do Visual Studio.

Observação

O Visual Studio coleta alguns eventos automaticamente do ETW ou EventPipe, mesmo que eles não tenham sido configurados explicitamente. Se você vir eventos que não reconhece na coluna Nome do Provedor ou Nome do Evento e quiser filtrá-los, use o ícone de filtro à direita para selecionar apenas os eventos que deseja exibir.

PerfView

O PerfView é uma ferramenta de desempenho criada pela equipe do .NET que pode coletar e exibir rastreamentos ETW. Ele também pode exibir arquivos de rastreamento coletados por outras ferramentas em vários formatos. Neste tutorial, você coletará um rastreamento ETW do aplicativo de demonstração e examinará os eventos coletados no Visualizador de Eventos do PerfView.

Coletar um rastreamento

Baixe o PerfView na página de versões. Este tutorial foi feito com o PerfView versão 2.0.76, mas qualquer versão recente deve funcionar.
Inicie o PerfView.exe com permissões de administrador.

Observação

A coleta de rastreamento do ETW sempre exige permissões de administrador. No entanto, se você estiver usando o PerfView para exibir apenas um rastreamento pré-existente, nenhuma permissão especial será necessária.
No menu Coletar, selecione Executar. Isso abre um novo diálogo na qual você inserirá o caminho para o aplicativo de demonstração.
Para configurar quais eventos são coletados, expanda Opções Avançadas na parte inferior do diálogo. Na caixa de texto Provedores Adicionais, insira provedores usando o formato de texto convencional descrito anteriormente. Nesse caso, você está inserindo "Demo: 1:4", o que significa bit de palavra-chave 1 (eventos Startup ) e detalhamento 4 (Informational).
Para iniciar o aplicativo e começar a coletar o rastreamento, selecione o botão Executar Comando. Quando o aplicativo é encerrado, o rastreamento PerfViewData.etl é salvo no diretório atual.

Exibir um rastreamento

Na caixa de texto suspensa da janela principal no canto superior esquerdo, selecione o diretório que contém o arquivo de rastreamento. Em seguida, clique duas vezes no arquivo de rastreamento no modo de exibição de árvore abaixo.
Para abrir o Visualizador de Eventos, clique duas vezes no item Eventos que aparece no modo de exibição de árvore abaixo do arquivo de rastreamento.
Todos os tipos de evento no rastreamento são mostrados na lista à esquerda. Clique duas vezes em um tipo de evento, como Demo\AppStarted, para mostrar todos os eventos desse tipo na tabela à direita.

Saiba mais

Para saber mais sobre como usar o PerfView, confira os tutoriais de vídeo do PerfView.

dotnet-trace

dotnet-trace é uma ferramenta de linha de comando de plataforma cruzada que pode coletar rastreamentos de aplicativos .NET Core usando o rastreamento EventPipe. Ele não dá suporte à exibição de dados de rastreamento, mas os rastreamentos coletados por ele podem ser exibidos por outras ferramentas, como PerfView ou Visual Studio. O dotnet-trace também dá suporte à conversão de seus rastreamentos de formato padrão .nettrace em outros formatos, como Chromium ou Speedscope.

Coletar um rastreamento

Baixe e instale o dotnet-trace.

Na linha de comando, execute o comando dotnet-trace collect:

E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Isso deve mostrar uma saída semelhante a:

E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Provider Name                           Keywords            Level               Enabled By
Demo                                    0x0000000000000001  Informational(4)    --providers

Launching: EventSourceDemo.exe
Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220317_021512.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

O dotnet-trace usa o formato de texto convencional para descrever a configuração do provedor no argumento --providers. Para obter mais opções sobre como fazer rastreamentos usando o dotnet-trace, confira os documentos do dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener é uma API .NET que pode ser usada no processo para receber retornos de chamada de eventos gerados por um System.Diagnostics.Tracing.EventSource. Essa API pode ser usada para criar ferramentas de log personalizadas ou para analisar os eventos na memória sem serializá-los.

Para usar EventListener, declare um tipo que derive de EventListener, invoque EnableEvents para assinar os eventos de alguma EventSource de interesse e substitua o OnEventWritten, que será chamado sempre que um novo evento estiver disponível. Muitas vezes, é útil substituir OnEventSourceCreated para descobrir quais objetos EventSource existem, mas isso não é necessário. Veja a seguir um exemplo de implementação de EventListener que é impressa no console quando as mensagens são recebidas:

Adicione este código ao aplicativo de demonstração.

class ConsoleWriterEventListener : EventListener
{
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        if(eventSource.Name == "Demo")
        {
            EnableEvents(eventSource, EventLevel.Informational);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
    }
}

Modifique o método Main para criar uma instância do novo ouvinte.

public static void Main(string[] args)
{
    ConsoleWriterEventListener listener = new ConsoleWriterEventListener();

    DemoEventSource.Log.AppStarted("Hello World!", 12);
    DemoEventSource.Log.DebugMessage("Got here");
    DemoEventSource.Log.DebugMessage("finishing startup");
    DemoEventSource.Log.RequestStart(3);
    DemoEventSource.Log.RequestStop(3);
}

Compile e execute o aplicativo. Anteriormente, ela não tinha nenhuma saída, mas agora ela grava os eventos no console:
```
3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop
```

Compartilhar via

Coletar e exibir rastreamentos EventSource

Aplicativo de exemplo

Configurar quais eventos coletar

Convenções para descrever a configuração do provedor

Visual Studio

Coletar um rastreamento

Exibir um rastreamento

PerfView

Coletar um rastreamento

Exibir um rastreamento

Saiba mais

dotnet-trace

Coletar um rastreamento

EventListener

Recursos adicionais