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

Статья
08/23/2023

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

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

Синтаксис

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
  [in]           TRACEHANDLE              TraceHandle,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Параметры

[in] ProviderId

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

[in, optional] SourceId

ИДЕНТИФИКАТОР GUID, который может однозначно идентифицировать источник этого запроса конфигурации, или значение NULL , если идентификатор источника не требуется (эквивалентно присвоению свойству SourceId значения &GUID_NULL). Если указано, это значение используется в качестве параметра SourceId при вызове EnableCallback поставщика.

Примечание

Не всегда существует прямое сопоставление между вызовом EnableTrace и соответствующим вызовом EnableCallback поставщика. Например, если для еще не зарегистрированного поставщика вызывается EnableTrace , вызов EnableCallback будет отложен до тех пор, пока не будет выполнена регистрация, а если сеанс потребителя трассировки остановлен, etW вызовет EnableCallback , даже если соответствующий вызов EnableTrace не был. В таких случаях enableTrace будет вызываться с параметромSourceId, для GUID_NULL.

[in] TraceHandle

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

[in] IsEnabled

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

[in] Level

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

Корпорация Майкрософт определяет семантику уровней 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] MatchAnyKeyword

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

[in] MatchAllKeyword

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

Это значение часто устанавливается равным 0.

[in] EnableProperty

Флаги, указывающие специальные поведения, которые должна включить среда выполнения трассировки событий Windows при сборе событий от этого поставщика. Чтобы включить специальные варианты поведения, укажите один или несколько следующих флагов. В противном случае задайте для EnableProperty значение 0.

Примечание

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

Значение	Значение
EVENT_ENABLE_PROPERTY_SID	Включите идентификатор безопасности (SID) пользователя в расширенные данные.
EVENT_ENABLE_PROPERTY_TS_ID	Включите идентификатор сеанса терминала в расширенные данные.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	Сеанс трассировки не должен записывать события с ключевое слово 0.

[in, optional] EnableFilterDesc

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

Сеанс может вызывать функцию TdhEnumerateProviderFilters для поиска фильтров, для которых поставщик зарегистрировал поддержку.

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

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

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

ERROR_INVALID_PARAMETER

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

Вы не сможете обновить уровень, если поставщик не зарегистрирован.
ERROR_NO_SYSTEM_RESOURCES

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

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

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

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

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

В большинстве случаев вызов EnableTraceEx можно преобразовать в EnableTraceEx2 следующим образом:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

В более сложных сценариях вызов EnableTraceEx можно преобразовать в EnableTraceEx2 следующим образом:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

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

Требования


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

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

StartTrace

EnableTraceEx2