Partilhar via

Recolher e Ver Rastreios do EventSource

  • Artigo

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

O guia de Introdução mostrou-lhe como criar um EventSource mínimo e recolher eventos num ficheiro de rastreio. Este tutorial mostra como diferentes ferramentas podem configurar que eventos são recolhidos num rastreio e, em seguida, ver os rastreios.

Aplicação de exemplo

Irá utilizar a seguinte aplicação de exemplo que gera eventos para este tutorial. Compile uma aplicação de consola .NET com o seguinte 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 os eventos a recolher

A maioria das ferramentas de recolha de eventos utiliza estas opções de configuração para decidir que eventos devem ser incluídos num rastreio:

  • Nomes de fornecedores – esta é uma lista de um ou mais nomes do EventSource. Apenas os eventos definidos em EventSources nesta lista são elegíveis para serem incluídos. Para recolher eventos da classe DemoEventSource na aplicação de exemplo anterior, teria de incluir o nome "Demo" do EventSource na lista de nomes de fornecedores.
  • Nível de verbosidade do evento – para cada fornecedor, pode definir um nível de verbosidade e os eventos com verbosidade superior a esse nível serão excluídos do rastreio. Se especificou que o fornecedor de "Demonstração" na aplicação de exemplo anterior deve ser recolhido ao nível da verbosidade informativa, o evento DebugMessage será excluído porque tem um nível mais elevado. Especificar EventLevel LogAlways(0) é um caso especial que indica que devem ser incluídos eventos de qualquer nível de verbosidade.
  • Palavras-chave do evento – para cada fornecedor, pode definir um conjunto de palavras-chave e apenas serão incluídos eventos marcados com, pelo menos, uma das palavras-chave. Na aplicação de exemplo acima, se tiver especificado a palavra-chave Arranque, apenas os eventos AppStarted e DebugMessage seriam incluídos. Se não forem especificadas palavras-chave, este é um caso especial e significa que os eventos com qualquer palavra-chave devem ser incluídos.

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

Embora cada ferramenta determine a sua própria interface de utilizador para definir a configuração do rastreio, existe uma convenção comum que muitas ferramentas utilizam ao especificar a configuração como uma cadeia de texto. A lista de fornecedores é especificada como uma lista delimitada por ponto e vírgula e cada elemento do fornecedor na lista consiste em nome, palavras-chave e nível separado por dois pontos. Por exemplo, "Demonstração:3:5" identifica o EventSource com o nome "Demonstração" com a máscara de bits de palavra-chave 3 (o Startup bit e o Requests bit) e EventLevel 5, que é Verbose. Muitas ferramentas também lhe permitem omitir o nível e as palavras-chave se não for pretendida qualquer filtragem de nível ou palavra-chave. Por exemplo, "Demonstração::5" apenas faz filtragem baseada em nível, "Demonstração:3" apenas faz filtragem baseada em palavras-chave e "Demonstração" não faz filtragem de nível ou palavra-chave.

Visual Studio

O gerador de perfis do Visual Studio suporta rastreios de recolha e visualização. Também pode ver rastreios que foram recolhidos antecipadamente por outras ferramentas, como dotnet-trace.

Recolher um rastreio

A maioria das ferramentas de criação de perfis do Visual Studio utiliza conjuntos predefinidos de eventos que servem uma finalidade específica, como analisar a utilização ou as alocações da CPU. Para recolher um rastreio com eventos personalizados, irá utilizar a ferramenta Visualizador de Eventos .

  1. Para abrir o Gerador de Perfis de Desempenho no Visual Studio, selecione Alt+F2.

  2. Selecione a caixa de verificação Visualizador de Eventos .

    Visualizador de Eventos do Visual Studio

  3. Selecione o ícone de engrenagem pequena à direita do Visualizador de Eventos para abrir a janela de configuração.

    Na tabela abaixo fornecedores adicionais, adicione uma linha para cada fornecedor que pretende configurar clicando na caixa de verificação Ativado e, em seguida, introduzindo o nome do fornecedor, palavras-chave e nível. Não precisa de introduzir o GUID do fornecedor; é calculado automaticamente.

    Definições do Visualizador de Eventos do Visual Studio

  4. Selecione OK para confirmar as definições de configuração.

  5. Selecione Iniciar para começar a executar a aplicação e recolher registos.

  6. Selecione Parar Recolha ou saia da aplicação para parar de recolher registos e mostrar os dados recolhidos.

Ver um rastreio

O Visual Studio pode ver os rastreios recolhidos por si próprio ou pode ver os rastreios recolhidos noutras ferramentas. Para ver rastreios de outras ferramentas, utilize Abrir Ficheiro> e selecione um ficheiro de rastreio no seletor de ficheiros. O gerador de perfis do Visual Studio suporta ficheiros .etl (formato padrão do ETW), ficheiros .nettrace (formato padrão do EventPipe) e ficheiros .diagsession (formato padrão do Visual Studio). Para obter informações sobre como trabalhar com ficheiros de rastreio no Visual Studio, veja a documentação do Visual Studio.

Rastreio ETW do Visualizador de Eventos do Visual Studio

Nota

O Visual Studio recolhe automaticamente alguns eventos do ETW ou do EventPipe, mesmo que não tenham sido explicitamente configurados. Se vir eventos que não reconhece na coluna Nome do Fornecedor ou Nome do Evento e pretende filtre-os, utilize o ícone de filtro à direita para selecionar apenas os eventos que pretende ver.

PerfView

O PerfView é uma ferramenta de desempenho criada pela equipa do .NET que pode recolher e ver rastreios ETW. Também pode ver ficheiros de rastreio recolhidos por outras ferramentas em vários formatos. Neste tutorial, irá recolher um rastreio ETW da aplicação de demonstração e, em seguida, examinar os eventos recolhidos no visualizador de eventos do PerfView.

Recolher um rastreio

  1. Transfira o PerfView a partir da página de lançamentos. Este tutorial foi feito com a versão 2.0.76 do PerfView, mas qualquer versão recente deverá funcionar.

  2. Comece PerfView.exe com permissões de administrador.

    Nota

    A recolha de rastreio ETW requer sempre permissões de administrador. No entanto, se estiver a utilizar apenas o PerfView para ver um rastreio pré-existente, não são necessárias permissões especiais.

    Janela Principal do PerfView

  3. No menu Recolher , selecione Executar. Esta ação abre uma nova caixa de diálogo onde irá introduzir o caminho para a aplicação de demonstração.

    Caixa de Diálogo Executar do PerfView

  4. Para configurar os eventos que são recolhidos, expanda Opções Avançadas na parte inferior da caixa de diálogo. Na caixa de texto Fornecedores Adicionais , introduza fornecedores com o formato de texto convencional descrito anteriormente. Neste caso, está a introduzir "Demonstração:1:4", o que significa a palavra-chave bit 1 (Startup eventos) e verbosidade 4 (Informational).

    Definições Avançadas da Caixa de Diálogo Executar Do PerfView

  5. Para iniciar a aplicação e começar a recolher o rastreio, selecione o botão Executar Comando . Quando a aplicação sair, o rastreio PerfViewData.etl é guardado no diretório atual.

Ver um rastreio

  1. Na caixa de texto pendente da janela principal no canto superior esquerdo, selecione o diretório que contém o ficheiro de rastreio. Em seguida, faça duplo clique no ficheiro de rastreio na vista de árvore abaixo.

    PerfView Janela Principal Selecionando um rastreio

  2. Para apresentar o visualizador de Eventos, faça duplo clique no item Eventos que aparece na vista de árvore abaixo do ficheiro de rastreio.

    Visualizador de Eventos do PerfView

  3. Todos os tipos de eventos no rastreio são apresentados na lista à esquerda. Faça duplo clique num tipo de evento, como Demo\AppStarted, para mostrar todos os eventos desse tipo na tabela à direita.

    PerfView Events Viewer AppStarted events (Eventos do PerfView Events Viewer AppStarted)

Saber mais

Para saber mais sobre como utilizar o PerfView, consulte os tutoriais em vídeo do PerfView.

dotnet-trace

dotnet-trace é uma ferramenta de linha de comandos para várias plataformas que pode recolher rastreios de aplicações .NET Core com o rastreio EventPipe . Não suporta a visualização de dados de rastreio, mas os rastreios recolhidos podem ser visualizados por outras ferramentas, como o PerfView ou o Visual Studio. o dotnet-trace também suporta a conversão dos respetivos rastreios de formato .nettrace predefinidos noutros formatos, como Chromium ou Speedscope.

Recolher um rastreio

  1. Transfira e Instale o dotnet-trace.

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

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

    Esta ação deve mostrar um resultado 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.

    dotnet-trace utiliza o formato de texto convencional para descrever a configuração do fornecedor no --providers argumento . Para obter mais opções sobre como efetuar rastreios com o dotnet-trace, veja os documentos dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener é uma API .NET que pode ser utilizada a partir do processo para receber chamadas de retorno para eventos gerados por um System.Diagnostics.Tracing.EventSource. Esta API pode ser utilizada para criar ferramentas de registo personalizadas ou para analisar os eventos na memória sem nunca os serializar.

Para utilizar EventListener, declare um tipo que deriva de EventListener, invoque EnableEvents para subscrever os eventos de qualquer 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 que objetos do EventSource existem, mas tal não é necessário. Segue-se um exemplo EventListener de implementação que é impresso na consola quando as mensagens são recebidas:

  1. Adicione este código à aplicação 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);
    }
}

  2. Modifique o Main método para criar uma instância do novo serviço de escuta.

    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);
}

  3. Compile e execute a aplicação. Anteriormente, não tinha saída, mas agora escreve os eventos na consola:

    3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop