Трассировка событий

Назначение

Трассировка событий для Windows (ETW) предоставляет программистам приложений возможность запускать и прекращать сеансы трассировки событий, инструментировать приложение для предоставления событий трассировки и использовать события трассировки. События трассировки содержат заголовок события и определяемые поставщиком данные, описывающие текущее состояние приложения или операции. События можно использовать для отладки приложения и выполнения анализа емкости и производительности.

Эта документация предназначена для приложений пользовательского режима, которые хотят использовать ETW. Сведения об инструментировании драйверов устройств, выполняемых в режиме ядра, см. в разделе Трассировка программного обеспечения WPP и Добавление трассировки событий для Kernel-Mode драйверов в наборе драйверов Windows (WDK).

Где применимо

Используйте ETW, если требуется инструментировать приложение, записывать события пользователя или ядра в файл журнала и использовать события из файла журнала или в режиме реального времени.

Аудитория разработчиков

Трассировка событий Windows разработана для разработчиков на C и C++, которые пишут приложения пользовательского режима.

Требования к среде выполнения

ETW входит в состав Microsoft Windows 2000 и более поздних версий. Сведения о том, какие операционные системы требуются для использования определенной функции, см. в разделе «требования» документации по функции.

Обработка трассировок трассировки событий Windows в коде .NET

Вы можете использовать API .NET трацепроцессинг для анализа трассировок трассировки событий Windows для приложений и других программных компонентов. Этот API внутренне используется в корпорации Майкрософт для анализа данных ETW, созданных в системе разработки Windows, а также для включения нескольких таблиц в анализаторе производительности Windows. Этот API доступен в виде пакета NuGet.

Сведения о трассировке событий

Трассировка событий для Windows (ETW) — это эффективный механизм трассировки на уровне ядра, позволяющий регистрировать события ядра или приложения в файле журнала. Вы можете использовать события в режиме реального времени или из файла журнала, используя их для отладки приложения или для определения того, где в приложении возникают проблемы с производительностью.

ETW позволяет динамически включать или отключать трассировку событий, позволяя выполнять подробную трассировку в рабочей среде без необходимости перезапуска компьютера или приложения.

API трассировки событий разбивается на три отдельных компонента:

• Контроллеры, которые запускают и останавливают сеанс трассировки событий и включают поставщиков.
• Поставщики, которые предоставляют события
• Потребители, которые используют события

На следующей диаграмме показана модель трассировки событий.

Контроллеры

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

Поставщики

Поставщики — это приложения, которые содержат Инструментирование трассировки событий. После того как поставщик регистрируется, контроллер может включить или отключить трассировку событий в поставщике. Поставщик определяет его интерпретацию включения или отключения. Как правило, включенный поставщик создает события, а отключенный поставщик — нет. Это позволяет добавлять в приложение трассировку событий, не требуя, чтобы она создавала события все время.

Хотя модель ETW разделяет контроллер и поставщика на отдельные приложения, приложение может включать оба компонента.

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

Типы поставщиков

Существует четыре основных типа поставщиков: поставщики MOF (классические), поставщики WPP, поставщики на основе манифестов и поставщики Трацелоггинг. При написании приложений для Windows Vista или более поздней версии, которые не нуждаются в поддержке устаревших систем, следует использовать поставщик на основе манифеста или поставщик Трацелоггинг.

Поставщики MOF (классические):

• Используйте функции регистертрацегуидс и TraceEvent для регистрации и записи событий.
• Используйте классы MOF для определения событий, чтобы потребители узнают, как их использовать.
• Может быть включено только одним сеансом трассировки за раз.

Поставщики WPP:

• Используйте функции регистертрацегуидс и TraceEvent для регистрации и записи событий.
• Имеют связанные файлы ТМФ (скомпилированные в PDB-файл), содержащие сведения о декодировании, выведенные из проверки препроцессора на наличие инструментирования WPP в исходном коде.
• Может быть включено только одним сеансом трассировки за раз.

Поставщики на основе манифеста:

• Используйте EventRegister и EventWrite для регистрации и записи событий.
• Используйте манифест для определения событий, чтобы потребители узнают, как их использовать.
• Может быть включено до восьми сеансов трассировки одновременно.

Поставщики трацелоггинг :

• Используйте трацелоггингрегистер и трацелоггингврите для регистрации и записи событий.
• Используйте самостоятельное описание событий, чтобы сами события содержали все необходимые сведения для их использования.
• Может быть включено до восьми сеансов трассировки одновременно.

Все поставщики событий используют семейство интерфейсов API для отслеживания событий (TraceEvent для устаревших технологий и EventWrite / евентвритикс для более новых версий). Поставщики событий просто отличаются тем, какие типы полей хранятся в полезных данных события, и где они хранят связанные сведения о декодировании событий.

Потребители

Потребители — это приложения, которые выбирают один или несколько сеансов трассировки событий в качестве источника событий. Потребитель может запрашивать события одновременно из нескольких сеансов трассировки событий; система предоставляет события в хронологическом порядке. Потребители могут получать события, хранящиеся в файлах журнала, или из сеансов, которые доставляют события в режиме реального времени. При обработке событий потребитель может указать время начала и окончания, и будут доставлены только те события, которые произошли в заданный промежуток времени.

Дополнительные сведения см. в разделе Использование событий.

Отсутствующие события

PerfMon, диагностика системы и другие системные средства могут сообщать об отсутствующих событиях в журнале событий и указывать, что параметры трассировки событий для Windows (ETW) могут быть неоптимальными. События могут быть утрачены по ряду причин:

Общий размер события больше 64 КБ. Сюда входит заголовок ETW, а также данные или полезные данные. Пользователь не контролирует эти отсутствующие события, так как размер события настраивается приложением.

Размер буфера ETW меньше, чем общий размер события. Пользователь не может управлять этими отсутствующими событиями, так как размер события настраивается приложением для регистрации событий.

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

При ведении журнала в файл он работает слишком долго, чтобы не отследить скорость ведения журнала.

По любой из этих причин сообщите эти проблемы поставщику приложения или службы, которые создают события. Эти проблемы может устранить только разработчик приложения или служба, записывая в журнал события. Если в службе журнала событий содержатся сведения об отсутствующих событиях, это может указывать на проблему с конфигурацией службы журнала событий. Пользователь может иметь ограниченную возможность увеличить максимальное дисковое пространство, которое будет использоваться службой журнала событий, что может уменьшить количество отсутствующих событий.

Event Tracing

Purpose

Event Tracing for Windows (ETW) provides application programmers the ability to start and stop event tracing sessions, instrument an application to provide trace events, and consume trace events. Trace events contain an event header and provider-defined data that describes the current state of an application or operation. You can use the events to debug an application and perform capacity and performance analysis.

This documentation is for user-mode applications that want to use ETW. For information about instrumenting device drivers that run in kernel mode, see WPP Software Tracing and Adding Event Tracing to Kernel-Mode Drivers in the Windows Driver Kit (WDK).

Where applicable

Use ETW when you want to instrument your application, log user or kernel events to a log file, and consume events from a log file or in real time.

Developer audience

ETW is designed for C and C++ developers who write user-mode applications.

Run-time requirements

ETW is included in Microsoft WindowsВ 2000 and later. For information about which operating systems are required to use a particular function, see the Requirements section of the documentation for the function.

Process ETW traces in .NET code

You can use the .NET TraceProcessing API to analyze ETW traces for your applications and other software components. This API is used internally at Microsoft to analyze ETW data produced the Windows engineering system, and it is also used to power several tables in Windows Performance Analyzer. This API is available as a NuGet package.

About Event Tracing

Event Tracing for Windows (ETW) is an efficient kernel-level tracing facility that lets you log kernel or application-defined events to a log file. You can consume the events in real time or from a log file and use them to debug an application or to determine where performance issues are occurring in the application.

ETW lets you enable or disable event tracing dynamically, allowing you to perform detailed tracing in a production environment without requiring computer or application restarts.

The Event Tracing API is broken into three distinct components:

• Controllers, which start and stop an event tracing session and enable providers
• Providers, which provide the events
• Consumers, which consume the events

The following diagram shows the event tracing model.

Controllers

Controllers are applications that define the size and location of the log file, start and stop event tracing sessions, enable providers so they can log events to the session, manage the size of the buffer pool, and obtain execution statistics for sessions. Session statistics include the number of buffers used, the number of buffers delivered, and the number of events and buffers lost.

Providers

Providers are applications that contain event tracing instrumentation. After a provider registers itself, a controller can then enable or disable event tracing in the provider. The provider defines its interpretation of being enabled or disabled. Generally, an enabled provider generates events, while a disabled provider does not. This lets you add event tracing to your application without requiring that it generate events all the time.

Although the ETW model separates the controller and provider into separate applications, an application can include both components.

For more information, see Providing Events.

Types of Providers

There are four main types of providers: MOF (classic) providers, WPP providers, manifest-based providers, and TraceLogging providers. You should use a manifest-based provider or a TraceLogging provider if you are writing applications for WindowsВ Vista or later that do not need to support legacy systems.

MOF (classic) providers:

• Use the RegisterTraceGuids and TraceEvent functions to register and write events.
• Use MOF classes to define events so that consumers know how to consume them.
• Can be enabled by only one trace session at a time.

WPP providers:

• Use the RegisterTraceGuids and TraceEvent functions to register and write events.
• Have associated TMF files (compiled into a binary’s .pdb) containing decoding information inferred from the preprocessor’s scan of WPP instrumentation in source code.
• Can be enabled by only one trace session at a time.

Manifest-based providers:

• Use EventRegister and EventWrite to register and write events.
• Use a manifest to define events so that consumers know how to consume them.
• Can be enabled by up to eight trace sessions simultaneously.

TraceLogging providers:

• Use TraceLoggingRegister and TraceLoggingWrite to register and write events.
• Use self-describing events so that the events themselves contain all required information for consuming them.
• Can be enabled by up to eight trace sessions simultaneously.

All event providers fundamentally use the Event Tracing family of APIs (TraceEvent for legacy technologies and EventWrite/EventWriteEx for newer ones). Event providers simply differ in what field types they store in event payloads and where they store the associated event decoding information.

Consumers

Consumers are applications that select one or more event tracing sessions as a source of events. A consumer can request events from multiple event tracing sessions simultaneously; the system delivers the events in chronological order. Consumers can receive events stored in log files, or from sessions that deliver events in real time. When processing events, a consumer can specify start and end times, and only events that occur in the specified time frame will be delivered.

For more information, see Consuming Events.

Missing Events

Perfmon, System Diagnostics, and other system tools may report on missing events in the Event Log and indicate that the settings for Event Tracing for Windows (ETW) may not be optimal. Events can be lost for a number of reasons:

The total event size is greater than 64K. This includes the ETW header plus the data or payload. A user has no control over these missing events since the event size is configured by the application.

The ETW buffer size is smaller than the total event size. A user has no control over these missing events since the event size is configured by the application logging the events.

For real-time logging, the real-time consumer is not consuming events fast enough or is not present altogether and then the backing file is filling up. This can result if the Event Log service is stopped and started when events are being logged. A user has no control over these missing events.

When logging to a file, the disk is too slow to keep up with the logging rate.

For any of these reasons, please report these problems to the provider of the application or service that is generating the events. These issues can only be fixed by the application developer or the service logging the events. If the missing events are being reported in the Event Log Service, this may indicate a problem with the configuration of the Event Log service. The user may have some limited ability to increase the maximum disk space to be used by the Event Log Service which may reduce the number of missing events.