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.EventSourceo , coletar eventos em um arquivo de rastreamento, exibir o rastreamento e entender os conceitos básicos do EventSource.
Nota
Muitas tecnologias que se integram com o EventSource usam os termos 'Tracing' e 'Traces' em vez 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);
Essa linha de código tem um objeto de log (DemoEventSource.Log), um método que representa o evento a ser registrado (AppStarted) e, opcionalmente, alguns parâmetros de evento fortemente tipados (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 de "Demo", especificada na EventSourceAttribute definição da 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 verbosidade e palavras-chave.
Para obter mais informações e práticas recomendadas sobre a criação de 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 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 Publish-subscribe, 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 assinatura do Rastreamento de Eventos para Windows (ETW) e do EventPipe (somente .NET Core). Assinantes personalizados também podem ser criados usando a System.Diagnostics.Tracing.EventListener API.
Esta demonstração mostra um exemplo de EventPipe para aplicativos .NET Core. Para saber mais sobre mais opções, consulte Coletando e exibindo rastreamentos de eventos. O 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 rastreamentos EventPipe.
- Baixar e instalar 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 ativado e saída do arquivo EventSourceDemo.exe_20220303_001619.nettracede rastreamento.
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 e à direita você pode 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 exibição na interface do usuário se estiverem distraídos. 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.
