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

Статья
06/12/2024

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

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

Синтаксис

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [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.

TraceId

[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

Флаги, указывающие особое поведение, которое среда выполнения ETW должна включать при сборе событий от этого поставщика. Чтобы включить специальные варианты поведения, укажите один или несколько следующих флагов. В противном случае задайте для 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

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

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

Синтаксис

Параметры

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

Комментарии

Требования

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

Обратная связь

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