Introdução ao EventSource
Este artigo se aplica a: ✔️ .NET Core 3.1 e versões posteriores ✔️ .NET Framework 4.5 e versões posteriores
Este passo a passo mostra como registrar um novo evento com System.Diagnostics.Tracing.EventSource, 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'. Aqui, o significado é o mesmo.
Registrar um evento
O objetivo de EventSource é permitir que os desenvolvedores do .NET escrevam código como este para registrar um evento:
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 detalhamento, IDs de evento, modelos de mensagem nem qualquer outra coisa que não precise estar no site de chamada. Todas essas outras informações sobre os 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 evento chamado 'AppStarted' é definido pelo método AppStarted(). Sempre que o código invocar o método AppStarted, outro evento AppStarted será registrado no rastreamento se o evento estiver habilitado. Estes 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. É usado como um namespace para os eventos. Os nomes de eventos e as IDs só precisam ser exclusivos dentro do escopo de sua origem. Aqui, o nome da origem é "Demo", especificado no EventSourceAttribute na definição de classe. O nome de origem também é 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 melhores práticas sobre como criar eventos, consulte Instrumentando código para criar eventos.
Coletar e exibir um arquivo de rastreamento
Não há nenhuma configuração necessária no código que descreve 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. 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 assinados. 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 API System.Diagnostics.Tracing.EventListener.
Essa demonstração mostra um exemplo de EventPipe para aplicativos .NET Core. Para saber mais sobre as opções, confira Coletando e exibindo rastreamentos de eventos. EventPipe é uma tecnologia de rastreamento aberta e multiplataforma incorporada ao runtime do .NET Core para proporcionar 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 de EventPipe.
- Baixe e instale o dotnet-trace
- Compile o aplicativo de console acima. Essa demonstração pressupõe que o aplicativo seja nomeado EventSourceDemo.exe e esteja 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.
Esse 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.
