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

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

  • Статья

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

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

Синтаксис

ULONG WMIAPI EnableTrace(
  [in] ULONG           Enable,
  [in] ULONG           EnableFlag,
  [in] ULONG           EnableLevel,
  [in] LPCGUID         ControlGuid,
       CONTROLTRACE_ID TraceId
);

Параметры

[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 элемента управления (идентификатор поставщика) поставщика событий, который требуется включить или отключить.

TraceId

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

Если функция выполнена успешно, возвращаемое значение будет 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