Начало работы с EventSource

Эта статья относится к: ✔️ .NET Core 3.1 и более поздних версий ✔️ .NET Framework 4.5 и более поздних версий

В этом пошаговом руководстве показано, как регистрировать новое событие с помощью System.Diagnostics.Tracing.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 использует шаблон публикации и подписки на, который требует, чтобы подписчики указывали на события, которые должны быть включены и контролировать всю сериализацию для подписанных событий. EventSource поддерживает интеграцию для подписки из трассировки событий для Windows (ETW) и EventPipe (только .NET Core). Пользовательских подписчиков также можно создавать с помощью API System.Diagnostics.Tracing.EventListener.

В этой демонстрации показан пример EventPipe для приложений .NET Core. Для получения дополнительной информации см. статью Сбор и просмотр записей событий. EventPipe — это открытая и кроссплатформенная технология трассировки, встроенная в среду выполнения .NET Core, чтобы предоставить разработчикам .NET инструменты для сбора трассировок и переносимый компактный формат трассировки (*.nettrace-файлы). dotnet-trace — это командное средство для сбора трассировок EventPipe.

1. Скачайте и установите dotnet-trace.
2. Создайте консольное приложение выше. В этой демонстрации предполагается, что приложение называется 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, хотя их можно игнорировать и исключить из отображения в пользовательском интерфейсе, если они кажутся отвлекающими. Эти дополнительные события фиксируют некоторые сведения о процессе и JIT-коде, что позволяет Visual Studio восстановить трассировки стека событий.

Дополнительные сведения о EventSource

• код инструментирования для создания событий
• Сбор и просмотр трассировок событий