Начало работы с EventSource
Эта статья относится к : ✔️ .NET Core 3.1 и более поздних✔️ версий платформа .NET Framework версии 4.5 и более поздних версий.
В этом пошаговом руководстве показано, как регистрировать новое событие с System.Diagnostics.Tracing.EventSourceпомощью , собирать события в файле трассировки, просматривать трассировку и понимать основные понятия EventSource.
Примечание.
Многие технологии, которые интегрируются с EventSource, используют термины "Трассировка" и "Трассировки" вместо "Ведение журнала" и "Журналы". Смысл здесь тот же.
Регистрация события
Цель EventSource заключается в том, чтобы разработчики .NET могли писать код следующим образом, чтобы регистрировать событие:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Эта строка кода содержит объект ведения журнала (DemoEventSource.Log), метод, представляющий событие для журнала (AppStarted), а также при необходимости некоторые строго типизированные параметры события (HelloWorld! и 12). Нет уровней детализации, идентификаторов событий, шаблонов сообщений или других элементов, которые не должны находиться на сайте вызова. Все эти другие сведения о событиях записываются путем определения нового класса, производного от System.Diagnostics.Tracing.EventSource.
Ниже приведен полный минимальный пример:
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);
}
}
Класс DemoEventSource объявляет метод для каждого типа события, которое требуется регистрировать. В этом случае одно событие с именем AppStarted определяется методом AppStarted(). Каждый раз, когда код вызывает метод AppStarted, в трассировку записывается другое событие AppStarted, если это событие включено. Это некоторые данные, которые можно записать с каждым событием:
- Имя события — имя, определяющее тип события, зарегистрированного в журнал. Имя события будет идентично имени метода AppStarted в данном случае.
- Идентификатор события — числовый идентификатор, определяющий тип события, зарегистрированного в журнал. Это служит аналогичной роли имени, но может помочь в быстрой автоматической обработке журналов. Событие AppStarted имеет идентификатор 1, указанный в файле EventAttribute.
- Имя источника — имя EventSource, содержащего событие. Это используется в качестве пространства имен для событий. Имена событий и идентификаторы должны быть уникальными только в область источника. Здесь источник называется "Demo", указанный в EventSourceAttribute определении класса. Имя источника также часто называется именем поставщика.
- Аргументы — все значения аргументов метода сериализуются.
- Другие сведения . События также могут содержать метки времени, идентификаторы потоков, идентификаторы процессоров, идентификаторы действий, трассировки стека и метаданные событий, такие как шаблоны сообщений, уровни детализации и ключевое слово.
Дополнительные сведения и рекомендации по созданию событий см . в коде инструментирования для создания событий.
Сбор и просмотр файла трассировки
В коде нет требуемой конфигурации, описывающей, какие события должны быть включены, где должны отправляться зарегистрированные данные или какой формат должны храниться данные. Если вы запускаете приложение сейчас, он не будет создавать файл трассировки по умолчанию. EventSource использует шаблон publish-subscribe, который требует, чтобы подписчики указывали на события, которые должны быть включены, и управлять всеми сериализациями для подписанных событий. EventSource поддерживает интеграцию для подписки на трассировку событий для Windows (ETW) и EventPipe (только для .NET Core). Пользовательские подписчики также можно создать с помощью System.Diagnostics.Tracing.EventListener API.
В этой демонстрации показан пример EventPipe для приложений .NET Core. Дополнительные сведения см. в разделе "Сбор и просмотр трассировок событий". EventPipe — это открытая и кроссплатформенная технология трассировки, встроенная в среду выполнения .NET Core для предоставления разработчикам средств сбора трассировки .NET и переносимого компактного формата трассировки (*.nettrace-файлов). dotnet-trace — это средство командной строки, которое собирает трассировки EventPipe.
- Скачивание и установка dotnet-trace
- Создайте консольное приложение выше. В этой демонстрации предполагается, что приложение называется EventSourceDemo.exe и находится в текущем каталоге. В командной строке выполните следующие действия:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
В этом случае должны отображаться выходные данные, аналогичные следующим:
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.
Эта команда выполнила EventSourceDemo.exe со всеми событиями в параметре EventSource с поддержкой Demo и выводом файла EventSourceDemo.exe_20220303_001619.nettraceтрассировки.
Открытие файла в Visual Studio показывает события, которые были зарегистрированы.
В представлении списка вы увидите первое событие — это событие Demo/AppStarted. Текстовый столбец содержит сохраненные аргументы, столбец метки времени показывает, что событие произошло 27 мс после начала ведения журнала и справа от него можно увидеть вызовы. Другие события автоматически включены в каждой трассировке, собранной dotnet-trace, хотя их можно игнорировать и фильтровать из представления в пользовательском интерфейсе, если они отвлекают. Эти дополнительные события фиксируют некоторые сведения о процессе и коде, который позволяет Visual Studio восстановить трассировки стека событий.
