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

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

  • Статья

Функция ControlTrace сбрасывает, запрашивает, обновляет или останавливает указанный сеанс трассировки событий.

Синтаксис

ULONG WMIAPI ControlTraceW(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCWSTR                 InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Параметры

TraceId

[in] InstanceName

Имя сеанса трассировки событий или NULL. Необходимо указать InstanceName , если TraceHandle имеет значение 0.

Чтобы указать сеанс средства ведения журнала ядра NT, задайте для instanceNameзначение KERNEL_LOGGER_NAME.

[in, out] Properties

Указатель на инициализированную структуру EVENT_TRACE_PROPERTIES . Эта структура должна быть обнуляема перед установкой каких-либо полей.

Если ControlCode указывает EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY или EVENT_TRACE_CONTROL_FLUSH, необходимо задать только элементы Wnode.BufferSize, Wnode.Guid, LoggerNameOffset и LogFileNameOffset структуры EVENT_TRACE_PROPERTIES . Если сеанс является частным, необходимо также задать LogFileMode. Вы можете использовать максимальное имя сеанса (1024 символа) и максимальное имя файла журнала (1024 символа) для вычисления размера буфера и смещения, если они не известны.

Если ControlCode указывает EVENT_TRACE_CONTROL_UPDATE, во входных данных члены должны указать новые значения для обновляемого свойства. В выходных данных свойства содержат свойства и статистику для сеанса трассировки событий. Вы можете обновить следующие свойства.

  • EnableFlags: установите для этого элемента значение 0, чтобы отключить все системные поставщики. Задайте для этого параметра ненулевое значение, чтобы указать системных поставщиков, которые необходимо включить или оставить включенными. Это может быть ненулевым только для системных средств ведения журнала.

  • FlushTimer: задайте этот элемент, если вы хотите изменить время ожидания перед очисткой буферов. Если этот элемент равен 0, он не обновляется.

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

  • LogFileMode: задайте этот элемент, если вы хотите включить и выключить EVENT_TRACE_REAL_TIME_MODE . Чтобы отключить режим реального времени, установите для этого элемента значение 0. Чтобы включить режим реального времени (создание сеанса, записывающего на диск, а также доставку событий в режиме реального времени), задайте для этого элемента значение EVENT_TRACE_REAL_TIME_MODE , и он будет иметь значение OR с текущими режимами.

  • MaximumBuffers. Установите этот элемент, если вы хотите изменить максимальное число буферов, которые использует трассировка событий Windows. Если этот элемент равен 0, он не обновляется.

Для сеансов частного средства ведения журнала можно обновить только элементы LogFileNameOffset и FlushTimer .

Если вы используете новую инициализированную структуру EVENT_TRACE_PROPERTIES , обнулите структуру, а затем задайте Wnode.BufferSize, Wnode.Guid и Wnode.Flags и значения, которые требуется обновить.

При повторном использовании структуры EVENT_TRACE_PROPERTIES (т. е. с помощью структуры, переданной ранее в StartTrace или ControlTrace), обязательно установите для элемента LogFileNameOffset значение 0, если вы не изменяете имя файла журнала, и обязательно установите EVENT_TRACE_PROPERTIES. Wnode.Flags для WNODE_FLAG_TRACED_GUID.

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

[in] ControlCode

Запрошенная функция управления. Можно указать одно из следующих значений.

  • EVENT_TRACE_CONTROL_FLUSH: очищает активные буферы сеанса.

    Его можно использовать с сеансом в памяти (сеансом, запущенным с флагом EVENT_TRACE_BUFFERING_MODE ) для записи данных из трассировки в файл.

    Обычно очистка сеансов на основе файлов или сеансов в режиме реального времени не требуется, так как трассировка событий Windows автоматически очищает буфер при его заполнении (т. е. если у него нет места для следующего события), по истечении срока действия FlushTimer сеанса трассировки или при закрытии сеанса трассировки.

    Windows 2000: Это значение не поддерживается.

  • EVENT_TRACE_CONTROL_QUERY: извлекает свойства и статистику сеанса.

  • EVENT_TRACE_CONTROL_STOP: останавливает сеанс. Дескриптор сеанса больше недействителен.

  • EVENT_TRACE_CONTROL_UPDATE: обновляет свойства сеанса.

  • EVENT_TRACE_CONTROL_INCREMENT_FILE. Если в сеансе EVENT_TRACE_FILE_MODE_NEWFILEесть , обновляет сеанс, чтобы немедленно перейти к следующему файлу, а не дожидаться заполнения предыдущего файла. Поддерживается начиная с обновления Windows 10 за октябрь 2018 г.

  • EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME. Изменяет сеанс файлового режима на сеанс в режиме реального времени (включает доставку в режиме реального времени и отключает запись событий в ETL-файл). Поддерживается начиная с обновления Windows 10 за октябрь 2020 г.

Примечание

Очистка буферов или остановка сеанса трассировки из DllMain небезопасно (может привести к взаимоблокировкам).

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

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

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

  • ERROR_BAD_LENGTH

    Выполняется одно из следующих условий.

    • Элемент Wnode.BufferSizeсвойства указывает неправильный размер.
    • В свойствах недостаточно места, выделенного для хранения копии имени сеанса и имени файла журнала (если используется).

  • ERROR_INVALID_PARAMETER

    Выполняется одно из следующих условий.

    • Свойство имеет значение NULL.
    • InstanceName и TraceHandle имеют значение NULL.
    • InstanceName имеет значение NULL , а TraceHandle не является допустимым дескриптором.
    • Недопустимый элемент LogFileNameOffsetсвойства.
    • Недопустимый элемент LoggerNameOffsetсвойства .
    • Элемент LogFileModeсвойства задает недопустимое сочетание флагов.
    • Элементом Wnode.Guidсвойства являетсяSystemTraceControlGuid, но параметр InstanceName не KERNEL_LOGGER_NAMEимеет значения .

  • ERROR_BAD_PATHNAME

    В другом сеансе уже используется имя файла, указанное в элементе LogFileNameOffset структуры Properties .

  • ERROR_MORE_DATA

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

  • ERROR_ACCESS_DENIED

    Только пользователи с повышенными правами администратора, пользователи в группе Пользователи журнала производительности и службы, работающие под управлением LocalSystem, LocalService, NetworkService, могут управлять сеансами трассировки событий. Чтобы предоставить ограниченному пользователю возможность управлять сеансами трассировки, добавьте его в группу Пользователи журнала производительности. Только пользователи с правами администратора и службами, работающими под управлением LocalSystem, могут управлять сеансом средства ведения журнала ядра NT.

    Windows XP и Windows 2000: Любой пользователь может управлять сеансом трассировки.

  • ERROR_WMI_INSTANCE_NOT_FOUND

    Данный сеанс не выполняется.

  • ERROR_ACTIVE_CONNECTIONS

    При возвращении из вызова EVENT_TRACE_CONTROL_STOP это означает, что сеанс уже находится в процессе остановки.

Комментарии

Контроллеры трассировки событий вызывают эту функцию.

Эта функция заменяет функции FlushTrace, QueryTrace, StopTrace и UpdateTrace .

Примечание

Заголовок evntrace.h определяет ControlTrace как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Профессиональная [классические приложения | Приложения UWP]
Минимальная версия сервера Windows 2000 Server [классические приложения | Приложения UWP]
Целевая платформа Windows
Header evntrace.h
Библиотека Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP
DLL Sechost.dll в Windows 8.1 и Windows Server 2012; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP

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

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace