Introdução ao EventSource

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

Este passo a passo mostra como registrar um novo evento em log, coletar eventos em um arquivo de rastreamento, exibir o rastreamento e entender os conceitos básicos do EventSource.

Observação

Muitas tecnologias que se integram ao EventSource usam os termos 'Rastreamento' e 'Rastreamentos' em vez de 'Registro em log' e 'Logs'. O significado é o mesmo aqui.

Registrar um evento

O objetivo do EventSource é permitir que os desenvolvedores do .NET escrevam código como este para registrar um evento em log:

DemoEventSource.Log.AppStarted("Hello World!", 12);

Essa linha de código tem um objeto de registro em log (DemoEventSource.Log), um método que representa o evento para registrar em log (AppStarted) e, opcionalmente, alguns parâmetros de evento fortemente tipados (HelloWorld! e 12). Não há níveis de verbosidade, IDs de evento, modelos de mensagem ou qualquer outra coisa que não precise estar no site de chamada. Todas essas outras informações sobre eventos são escritas definindo uma nova classe derivada de System.Diagnostics.Tracing.EventSource.

Aqui está um exemplo mínimo completo:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
        }
    }

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

        [Event(1)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
    }
}

A classe DemoEventSource declara um método para cada tipo de evento que você deseja registrar. Nesse caso, um único evento chamado 'AppStarted' é definido pelo método AppStarted(). Toda vez que o código invocar o método AppStarted, um novo evento AppStarted será registrado no rastreamento, caso o evento esteja habilitado. Esses são alguns dos dados que podem ser capturados com cada evento:

• Nome do evento – um nome que identifica o tipo de evento que foi registrado. O nome do evento será idêntico ao nome do método, 'AppStarted' nesse caso.
• ID do evento – uma ID numérica que identifica o tipo de evento que foi registrado. Ela tem uma função semelhante à do nome, mas pode ajudar no processamento de log automatizado rápido. O evento AppStarted tem uma ID de 1, especificada no EventAttribute.
• Nome da origem – o nome do EventSource que contém o evento. Isso é usado como um namespace para eventos. Os nomes de eventos e as IDs só precisam ser exclusivos dentro do escopo de sua origem. Aqui, a origem é denominada "Demo" e está especificada na definição de classe EventSourceAttribute. O nome de origem também é comumente conhecido como um nome de provedor.
• Argumentos – todos os valores de argumento do método são serializados.
• Outras informações: os eventos também podem conter carimbos de data/hora, IDs de thread, IDs do processador, IDs de atividade, rastreamentos de pilha e metadados de evento, como modelos de mensagem, níveis de detalhamento e palavras-chave.

Para obter mais informações e práticas recomendadas sobre como criar eventos, consulte o código de instrumentação para criar eventos.

Coletar e exibir um arquivo de rastreamento

Não há nenhuma configuração necessária no código que descreva em quais eventos devem ser habilitados, para onde os dados registrados devem ser enviados ou em qual formato os dados devem ser armazenados. Se você executar o aplicativo agora, ele não produzirá nenhum arquivo de rastreamento por padrão. O EventSource usa o padrão Publicar-assinar, que exige que os assinantes indiquem os eventos que devem ser habilitados e controlem toda a serialização para os eventos inscritos. O EventSource tem integrações para assinar o ETW (Rastreamento de Eventos para Windows) e o EventPipe (somente.NET Core). Assinantes personalizados também podem ser criados usando a System.Diagnostics.Tracing.EventListener API.

Essa demonstração mostra um exemplo de EventPipe para aplicativos .NET Core. Para saber mais sobre as opções, consulte Coletando e exibindo rastreamentos de eventos. O EventPipe é uma tecnologia de rastreamento aberta e multiplataforma integrada ao runtime do .NET Core para fornecer aos desenvolvedores do .NET ferramentas de coleta de rastreamento e um formato de rastreamento compacto portátil (arquivos *.nettrace). dotnet-trace é uma ferramenta de linha de comando que coleta rastreamentos eventPipe.

1. Baixe e instale o dotnet-trace.
2. Crie o aplicativo de console acima. Essa demonstração pressupõe que o aplicativo é nomeado EventSourceDemo.exe e está no diretório atual. Na linha de comando, execute:

>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

Isso deve mostrar uma saída semelhante a:

Provider Name                           Keywords            Level               Enabled By
Demo                                    0xFFFFFFFFFFFFFFFF  Verbose(5)          --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_20220303_001619.nettrace

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

Trace completed.

Este comando executou EventSourceDemo.exe com todos os eventos no EventSource 'Demo' habilitados e gerou o arquivo de rastreamento EventSourceDemo.exe_20220303_001619.nettrace. Abrir o arquivo no Visual Studio mostra os eventos que foram registrados.

No modo de exibição de lista, você pode ver que o primeiro evento é o evento Demo/AppStarted. A coluna de texto tem os argumentos salvos, a coluna de carimbo de data/hora mostra que o evento ocorreu 27 ms após o início do registro em log e, à direita, você pode ver a pilha de chamadas. Os outros eventos são habilitados automaticamente a cada rastreamento coletado pelo dotnet-trace, embora possam ser ignorados e filtrados da exibição na interface do usuário se estiverem causando distração. Esses eventos extras capturam algumas informações sobre o processo e o código com compilação JIT, o que permite ao Visual Studio reconstruir os rastreamentos de pilha do evento.

Saiba mais sobre EventSource

• Instrumentando código para criar eventos
• Coletando e exibindo rastreamentos de eventos