Функция EnableTrace (evntrace.h)

Статья
03/11/2023

Контроллер сеанса трассировки вызывает EnableTrace , чтобы настроить, как поставщик событий ETW записывает события в сеанс трассировки.

Эта функция является устаревшей. Функция EnableTraceEx2 заменяет эту функцию.

Синтаксис

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

Параметры

[in] Enable

Задайте значение 1, чтобы включить получение событий от поставщика или настроить параметры, используемые при получении событий от поставщика (например, для изменения уровня и ключевых слов). Задайте значение 0, чтобы отключить получение событий от поставщика.

[in] EnableFlag

32-разрядная битовая маска ключевых слов, определяющих категории событий, которые требуется записать поставщику. Поставщик обычно записывает событие, если ключевое слово биты события соответствуют любому из битов, заданных в этом значении, или если событие не имеет ключевое слово битов, в дополнение к критерию EnableLevel.

Примечание

Поставщики на основе EventRegister поддерживают 64-разрядные ключевые слова. Используйте EnableTraceEx2, чтобы включить поставщиков, использующих 64-разрядную маску MatchAnyKeyword .

[in] EnableLevel

Значение типа , указывающее максимальный уровень событий, которые требуется записать поставщику. Поставщик обычно записывает событие, если уровень события меньше или равен этому значению, в дополнение к выполнению условий EnableFlag .

Это значение должно находиться в диапазоне от 1 до 255. Корпорация Майкрософт определяет семантику уровней 1–5, как показано ниже. Более низкие значения указывают на более серьезные события. Каждое значение EnableLevel включает указанный уровень и все более серьезные уровни. Например, если указать TRACE_LEVEL_WARNING, потребитель будет получать предупреждения, ошибки и критические события.

Значение	Значение
TRACE_LEVEL_CRITICAL (1)	Аномальные события выхода или завершения
TRACE_LEVEL_ERROR (2)	События серьезных ошибок
TRACE_LEVEL_WARNING (3)	Предупреждающие события, такие как сбои выделения
TRACE_LEVEL_INFORMATION (4)	Информационные события без ошибок
TRACE_LEVEL_VERBOSE (5)	Подробные события диагностики

Константы TRACE_LEVEL определяются в файле evntrace.h. Эквивалентные WINMETA_LEVEL константы определяются в winmeta.h.

[in] ControlGuid

GUID элемента управления (идентификатор поставщика) поставщика событий, который требуется включить или отключить.

[in] TraceHandle

Дескриптор сеанса трассировки событий, для которого настраивается поставщик. Функция StartTrace возвращает этот дескриптор при запуске новой трассировки. Чтобы получить дескриптор существующей трассировки, используйте ControlTrace для запроса свойств трассировки на основе имени трассировки, а затем получите дескриптор из поля Wnode.HistoricalContext возвращаемых EVENT_TRACE_PROPERTIES данных.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.

ERROR_INVALID_PARAMETER

Выполняется одно из следующих условий.
- ControlGuid имеет значение NULL.
- TraceHandle имеет значение NULL.
ERROR_INVALID_FUNCTION

Вы не можете изменить флаги и уровень включения, если поставщик не зарегистрирован.
ERROR_WMI_GUID_NOT_FOUND

Поставщик не зарегистрирован. Возникает, когда kb307331 или Windows 2000 с пакетом обновления 4 (SP4) установлено, а поставщик не зарегистрирован. Чтобы избежать этой ошибки, необходимо сначала зарегистрировать поставщика.
ERROR_NO_SYSTEM_RESOURCES

Превышено количество сеансов трассировки, которые могут включить поставщик.
ERROR_ACCESS_DENIED

Только пользователи с правами администратора, пользователи в Performance Log Users группе и службы, работающие под LocalSystemуправлением , LocalServiceили NetworkService могут включать поставщики событий в сеанс между процессами. Чтобы предоставить ограниченному пользователю возможность включить поставщик событий, добавьте его в группу Performance Log Users или ознакомьтесь с разделом EventAccessControl.

Windows XP и Windows 2000: Любой пользователь может включить поставщик событий.

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

Эта функция является устаревшей. Для дополнительных функций новый код должен использовать EnableTraceEx2.

Следующие два вызова функций эквивалентны:

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Дополнительные сведения о семантике настройки поставщиков для сеанса см. в документации по EnableTraceEx2.

Требования


Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntrace.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

См. также раздел

StartTrace

EnableTraceEx2