Introdução ao EventSource
Este artigo aplica-se 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 de EventSource.
Observação
Muitas tecnologias que se integram com o sistema EventSource usam os termos 'Tracing' e 'Traces' no lugar de 'Logging' e 'Logs'. O significado é o mesmo aqui.
Registar um evento
O objetivo do EventSource é permitir que os desenvolvedores do .NET escrevam código como este para registrar um evento:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Esta linha de código tem um objeto de registro (DemoEventSource.Log), um método que representa o evento a ser registado (AppStarted) e, opcionalmente, alguns parâmetros de evento com tipos fortes (HelloWorld! e 12). Não há níveis de verbosidade, IDs de eventos, 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(). Cada vez que o código invoca 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' neste caso.
- ID do Evento - Uma ID numérica que identifica o tipo de evento que foi registrado. Isso tem uma função semelhante ao nome, mas pode ajudar no processamento rápido e automatizado de logs. O evento AppStarted tem uma ID de 1, especificada no EventAttribute.
- Nome da fonte - O nome do EventSource que contém o evento. Isso é usado como um namespace para eventos. Os nomes e IDs de eventos só precisam ser exclusivos dentro do escopo de sua origem. Aqui a fonte é chamada "Demo", especificada no EventSourceAttribute na definição de classe. O nome da fonte também é comumente referido 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 de processador IDs de atividade, rastreamentos de pilha e metadados de eventos, como modelos de mensagens, níveis de detalhamento e palavras-chave.
Para obter mais informações e práticas recomendadas sobre a criação de eventos, consulte 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 quais eventos devem ser habilitados, para onde os dados registrados devem ser enviados ou em que 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-subscrever, que exige que os subscritores indiquem os eventos que devem ser ativados e controlem toda a serialização para todos os eventos subscritos. O EventSource tem integrações para a subscrição de eventos a partir de Rastreamento de Eventos para Windows (ETW) e EventPipe (somente .NET Core). Assinantes personalizados também podem ser criados usando a API System.Diagnostics.Tracing.EventListener.
Esta demonstração mostra um EventPipe exemplo para aplicativos .NET Core. Para saber mais sobre outras opções, consulte Recolhendo e exibindo rastreamentos de eventos. EventPipe é uma tecnologia de rastreamento aberta e multiplataforma incorporada ao tempo de execução 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 rastros EventPipe.
- Transfira e instale dotnet-trace.
- Crie o aplicativo de console acima. Esta demonstração pressupõe que o aplicativo tem o nome 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 'Demo' EventSource ativados e produziu 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 guardados, a coluna de marca temporal mostra que o evento ocorreu 27 ms após o início do registo e à direita é possível ver a pilha de chamadas. Os outros eventos são ativados automaticamente em cada rastreamento coletado pelo dotnet-trace, embora possam ser ignorados e filtrados da interface do utilizador se forem distrativos. Esses eventos extras capturam algumas informações sobre o processo e o código jitted, o que permite que o Visual Studio reconstrua os rastreamentos da pilha de eventos.
