Сбор и просмотр трассировок источников событий

Статья
04/11/2023

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

В руководстве по началу работы показано, как создать минимальный источник событий и собрать события в файле трассировки. В этом руководстве показано, как различные средства могут настроить, какие события собираются в трассировке, а затем просмотреть трассировки.

Пример приложения

Вы будете использовать следующий пример приложения, создающего события для этого руководства. Скомпилируйте консольное приложение .NET, содержащее следующий код:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Настройка событий для сбора

Большинство средств сбора событий используют эти параметры конфигурации, чтобы решить, какие события следует включить в трассировку:

Имена поставщиков . Это список из одного или нескольких имен EventSource. Включать можно только события, определенные в eventSources в этом списке. Чтобы собирать события из класса DemoEventSource в предыдущем примере приложения, необходимо включить имя EventSource Demo в список имен поставщиков.
Уровень детализации событий. Для каждого поставщика можно определить уровень детализации, а события с детализацией выше этого уровня будут исключены из трассировки. Если вы указали, что поставщик Demo в предыдущем примере приложения должен собирать данные на уровне информационной детализации, событие DebugMessage будет исключено, так как оно имеет более высокий уровень. Указание EventLevel LogAlways(0) — это особый случай, который указывает, что следует включать события любого уровня детализации.
Ключевые слова события. Для каждого поставщика можно определить набор ключевых слов, и будут включены только события, помеченные по крайней мере одним из ключевых слов. В приведенном выше примере приложения, если вы указали ключевое слово запуска, будут включены только события AppStarted и DebugMessage. Если ключевые слова не указаны, это особый случай и означает, что должны быть включены события с любым ключевое слово.

Соглашения для описания конфигурации поставщика

Хотя каждое средство определяет собственный пользовательский интерфейс для настройки конфигурации трассировки, существует общее соглашение, используемое многими средствами при указании конфигурации в виде текстовой строки. Список поставщиков указывается в виде списка с разделителями с запятой, и каждый элемент поставщика в списке состоит из имени, ключевых слов и уровня, разделенных двоеточиями. Например, Demo:3:5 идентифицирует EventSource с именем Demo с ключевое слово битовой маской 3 (Startupбит и Requests бит) и EventLevel 5, то есть Verbose. Многие средства также позволяют опустить уровень и ключевые слова, если не требуется фильтрация уровня или ключевое слово. Например, demo::5 выполняет фильтрацию только на основе уровня, demo:3 — только ключевое слово фильтрацию, а demo — не ключевое слово или уровней.

Visual Studio

Профилировщик Visual Studio поддерживает как сбор, так и просмотр трассировок. Он также может просматривать трассировки, собранные заранее другими средствами, такими как dotnet-trace.

Сбор трассировки

Большинство средств профилирования Visual Studio используют предопределенные наборы событий, которые служат определенной цели, например анализ использования ЦП или выделений ресурсов. Чтобы собрать трассировку с настроенными событиями, используйте средство "Просмотр событий ".

Чтобы открыть профилировщик производительности в Visual Studio, выберите Alt F2+.
Установите флажок Средство просмотра событий.
Щелкните небольшой значок шестеренки справа от окна "Просмотр событий", чтобы открыть окно конфигурации.

В таблице ниже Дополнительные поставщики добавьте строку для каждого поставщика, который вы хотите настроить, установив флажок Включено , а затем введя имя поставщика, ключевые слова и уровень. Вам не нужно вводить GUID поставщика; он вычисляется автоматически.
Нажмите кнопку ОК , чтобы подтвердить параметры конфигурации.
Нажмите кнопку Пуск , чтобы начать запуск приложения и сбор журналов.
Выберите Остановить сбор или закройте приложение, чтобы остановить сбор журналов и отобразить собранные данные.

Просмотр трассировки

Visual Studio может просматривать собранные трассировки или просматривать трассировки, собранные в других средствах. Чтобы просмотреть трассировки из других средств, используйте команду Открыть файл> и выберите файл трассировки в средстве выбора файлов. Профилировщик Visual Studio поддерживает ETL-файлы (стандартный формат ETW), nettrace-файлы (стандартный формат EventPipe) и файлы DIAGSESSION (стандартный формат Visual Studio). Сведения о работе с файлами трассировки в Visual Studio см. в документации по Visual Studio.

Примечание

Visual Studio автоматически собирает некоторые события из трассировки событий Windows или EventPipe, даже если они не были настроены явным образом. Если вы видите события, которые не распознаете в столбце Имя поставщика или Имя события, и хотите отфильтровать их, используйте значок фильтра справа, чтобы выбрать только те события, которые требуется просмотреть.

PerfView

PerfView — это средство производительности, созданное командой .NET, которое может собирать и просматривать трассировки трассировки трассировки windows. Он также может просматривать файлы трассировки, собранные другими средствами в различных форматах. В этом руководстве вы соберете трассировку etW демонстрационного приложения , а затем изучите собранные события в средстве просмотра событий PerfView.

Сбор трассировки

Скачайте PerfView со страницы выпусков. Это руководство было выполнено с помощью PerfView версии 2.0.76, но любая из последних версий должна работать.
Начните PerfView.exe с разрешениями администратора.

Примечание

Для сбора трассировки трассировки Трассировки Windows всегда требуются разрешения администратора, однако если вы используете только PerfView для просмотра уже существующей трассировки, специальные разрешения не требуются.
В меню Сбор выберите Выполнить. Откроется новое диалоговое окно, в котором вы введете путь к демонстрационной версии приложения.
Чтобы настроить собираемые события, разверните дополнительные параметры в нижней части диалогового окна. В текстовом поле Дополнительные поставщики введите поставщики, использующие обычный текстовый формат , описанный выше. В этом случае вводится "Demo:1:4", что означает ключевое слово бит 1 (Startupсобытия) и детализацию 4 (Informational).
Чтобы запустить приложение и начать сбор трассировки, нажмите кнопку Выполнить команду . Когда приложение завершает работу, трассировка PerfViewData.etl сохраняется в текущем каталоге.

Просмотр трассировки

В раскрывающемся окне main в левом верхнем углу выберите каталог, содержащий файл трассировки. Затем дважды щелкните файл трассировки в древовидном представлении ниже.
Чтобы открыть средство просмотра событий, дважды щелкните элемент События , который отображается в древовидном представлении под файлом трассировки.
Все типы событий в трассировке отображаются в списке слева. Дважды щелкните тип события, например Demo\AppStarted, чтобы отобразить все события этого типа в таблице справа.

Подробнее

Дополнительные сведения об использовании PerfView см. в видеоруководках по PerfView.

dotnet-trace

dotnet-trace — это кроссплатформенное средство командной строки, которое может собирать трассировки из приложений .NET Core с помощью трассировки EventPipe . Он не поддерживает просмотр данных трассировки, но собранные трассировки могут просматриваться другими средствами, такими как PerfView или Visual Studio. dotnet-trace также поддерживает преобразование трассировок формата .nettrace по умолчанию в другие форматы, такие как Chromium или Speedscope.

Сбор трассировки

Скачайте и установите dotnet-trace.

В командной строке выполните команду dotnet-trace collect :

E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Результат должен выглядеть примерно так:

E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Provider Name                           Keywords            Level               Enabled By
Demo                                    0x0000000000000001  Informational(4)    --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_20220317_021512.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

dotnet-trace использует обычный текстовый формат для описания конфигурации поставщика в аргументе --providers . Дополнительные сведения о том, как выполнять трассировку с помощью dotnet-trace, см. в документации по dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener — это API .NET, который можно использовать из внутрипроцессного процесса для получения обратных вызовов для событий, System.Diagnostics.Tracing.EventSourceсозданных . Этот API можно использовать для создания пользовательских средств ведения журнала или для анализа событий в памяти без их сериализации.

Чтобы использовать EventListener, объявите тип, производный от EventListener, вызовите EnableEvents для подписки на события из любого интересующего объекта EventSource и переопределите OnEventWritten, который будет вызываться при каждом появлении нового события. Часто бывает полезно переопределить OnEventSourceCreated , чтобы определить, какие объекты EventSource существуют, но это необязательно. Ниже приведен пример EventListener реализации, которая выводится в консоль при получении сообщений:

Добавьте этот код в демонстрационную версию приложения.

class ConsoleWriterEventListener : EventListener
{
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        if(eventSource.Name == "Demo")
        {
            EnableEvents(eventSource, EventLevel.Informational);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
    }
}

Измените метод , Main чтобы создать экземпляр нового прослушивателя.

public static void Main(string[] args)
{
    ConsoleWriterEventListener listener = new ConsoleWriterEventListener();

    DemoEventSource.Log.AppStarted("Hello World!", 12);
    DemoEventSource.Log.DebugMessage("Got here");
    DemoEventSource.Log.DebugMessage("finishing startup");
    DemoEventSource.Log.RequestStart(3);
    DemoEventSource.Log.RequestStop(3);
}

Выполните сборку и запуск приложения. Ранее у него не было выходных данных, но теперь он записывает события в консоль:
```
3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop
```

Поделиться через

Сбор и просмотр трассировок источников событий

Пример приложения

Настройка событий для сбора

Соглашения для описания конфигурации поставщика

Visual Studio

Сбор трассировки

Просмотр трассировки

PerfView

Сбор трассировки

Просмотр трассировки

Подробнее

dotnet-trace

Сбор трассировки

EventListener

Дополнительные ресурсы