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

StartKernelTrace

  • Статья

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

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

Параметры

TraceHandle [out]
Хранит дескриптор в сеансе трассировки событий. Этот параметр имеет значение ноль, если дескриптор недопустим. Этот параметр не следует сравнивать с INVALID_HANDLE_VALUE. Не используйте этот дескриптор, если функция завершается сбоем.

Свойства [вход, выход]
Хранит указатель на структуру EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES настраивает определенные аспекты поведения сеанса.

Первым элементом структуры EVENT_TRACE_PROPERTIES является WNODE_HEADER структура, называемая здесь Wnode.

Следующая EVENT_TRACE_PROPERTIES. Для настройки элемента управления трассировки ядра необходимо задать элементы Wnode.

BufferSize
Этот элемент содержит общий размер (в байтах) памяти, выделенной для свойств сеанса трассировки событий. Размер памяти должен включать достаточно места для хранения следующих данных:

  • Структура EVENT_TRACE_PROPERTIES.

  • Строка имени сеанса.

  • Строка имени файла журнала.

Guid
Каждый сеанс трассировки должен иметь guid, определенный для ссылки на сеанс.

Для сеанса средства ведения журнала ядра NT этот элемент должен иметь значение SystemTraceControlGuid. Дополнительные сведения о константах режима ведения журнала см. в разделе Константы средства ведения журнала ядра NT.

ClientContext
Этот элемент задает разрешение часов, используемое при вычислении метки времени ведения журнала для каждого события. Значение по умолчанию для этого элемента — счетчик производительности запросов.

Можно указать одно из следующих значений.

  • 1: Счетчик производительности запросов (QPC). QPC предоставляет метку времени с высоким разрешением (100 наносекунд), но сравнительно дороже для извлечения. Используйте это разрешение, если у вас высокая частота событий или потребитель объединяет события из разных буферов. На старых компьютерах метка времени может быть неверной, так как счетчик иногда пропускается из-за ошибок оборудования.

  • 2: Системное время. Системное время предоставляет метку времени с низким разрешением (10 миллисекунда), но сравнительно дешевле для извлечения. Если объем событий большой, разрешение системного времени может быть недостаточно для определения последовательности событий. В этом случае набор событий будет иметь одинаковую метку времени, но порядок, в котором трассировка событий Windows доставляет события, может быть неправильной.

  • 3: Счетчик циклов ЦП. Счетчик ЦП предоставляет метку времени с максимальным разрешением и является наименее затратной для извлечения. Однако счетчик ЦП ненадежн и не должен использоваться в рабочей среде. Например, на некоторых компьютерах таймер изменяет частоту из-за изменения температуры и питания, а также при остановке в некоторых состояниях. Если оборудование не поддерживает этот тип часов, трассировка событий Windows использует системное время. В Windows Server 2003, Windows XP с пакетом обновления 1 (SP1) и Windows XP это значение не поддерживается. Он был представлен в Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2).

Флаги
Этот элемент должен содержать WNODE_FLAG_TRACED_GUID, чтобы указать, что структура содержит сведения о трассировке событий и отправляется в средство ведения журнала. WNODE_FLAG_TRACED_GUID определяется в Evntrace.h.

Необходимо также задать следующие EVENT_TRACE_PROPERTIES члены:

LogFileMode
Указывает, какие режимы ведения журнала будут использоваться в сеансе трассировки событий ядра. Этот элемент можно использовать, чтобы указать, что события должны быть записаны в файл журнала, потребитель в режиме реального времени или и то, и другое.

Этот элемент также можно использовать для указания того, что сеанс является частным сеансом средства ведения журнала. Можно указать один или несколько режимов. Список возможных режимов см. в разделе Константы режима ведения журнала.

Примечание Не указывайте ведение журнала в режиме реального времени, если только потребители в режиме реального времени не готовы использовать события. Если потребителей в режиме реального времени нет, события записываются в файл воспроизведения. Размер файла воспроизведения ограничен. Если ограничение достигнуто, новые события не записываются в файл журнала или файл воспроизведения. Функции ведения журнала завершаются сбоем при STATUS_LOG_FILE_FULL.

EnableFlags
Этот элемент используется только для сеансов средства ведения журнала ядра NT. Он определяет для средства ведения журнала ядра, какие события следует отслеживать. При использовании логического ИЛИ этот элемент может содержать одно или несколько значений. Помимо указанных событий, средство ведения журнала ядра также регистрирует события конфигурации оборудования.

В дополнение к флагам, предоставляемым EVENT_TRACE_PROPERTIES, доступны следующие флаги управления трассировки:

LogFileNameOffset
Это число представляет смещение от начала памяти, выделенной для структуры, до начала строки, завершающейся значением NULL, содержащей имя файла журнала.

Действительны следующие условия.

  • Расширение имени файла должно быть .etl.

  • Все папки в пути должны существовать.

  • Путь может быть относительным, абсолютным, локальным или удаленным.

  • Путь не должен содержать переменные среды, так как они не развернуты.

  • Пользователь, который инициирует трассировку, должен иметь разрешение на запись в папку.

  • Имя файла журнала может содержать не более 1024 символов.

  • Если для параметра LogFileMode задано значение EVENT_TRACE_PRIVATE_LOGGER_MODE или EVENT_TRACE_FILE_MODE_NEWFILE, необходимо выделить достаточно памяти, чтобы включить идентификатор процесса, добавляемый к имени файла для сеансов частного средства ведения журнала, и последовательный номер, добавляемый в файлы журнала, созданные в новом режиме журнала файлов.

  • Если вы не хотите регистрировать события в файл журнала (например, вы указываете только EVENT_TRACE_REAL_TIME_MODE), задайте для параметра LogFileNameOffset значение 0. Если указано только ведение журнала в режиме реального времени, а также указано смещение с допустимым именем файла журнала, имя файла журнала используется для создания последовательного файла журнала и событий журнала в файле журнала. Последовательный файл журнала также создается, если logFileMode равен нулю и вы указываете смещение с допустимым именем файла журнала.

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

  • Файлы трассировки создаются с помощью дескриптора безопасности по умолчанию. Это означает, что файл журнала будет иметь тот же ACL, что и родительский каталог. Если вы хотите ограничить доступ к файлам, создайте родительский каталог с соответствующими списками управления доступом.

LoggerNameOffset
Этот элемент представляет смещение от начала памяти, выделенной для структуры, до начала строки, завершающейся значением NULL, содержащей имя сеанса.

Действительны следующие условия.

  • Длина имени сеанса ограничена 1024 символами.

  • Имя сеанса не учитывает регистр и должно быть уникальным.

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

  • Имя сеанса должно находиться перед именем файла журнала в памяти. Имя файла журнала должно быть скопировано в область смещения. Эта функция записывает имя сеанса, определенное KERNEL_LOGGER_NAME.

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

Примечание Нет необходимости задавать имя средства ведения журнала в параметре LoggerNameOffset , так как эта функция всегда использует значение KERNEL_LOGGER_NAME для вызова StartKernelTrace. Эта функция проверяет, соответствует ли Wnode.GuidSystemTraceControlGuid; Если нет, возвращается ERROR_INVALID_PARAMETER. Если Wnode.Guid соответствует KernelRundownGuid, необходимо указать имя средства ведения журнала. KernelRundownGuid — это guid элемента управления, используемый для регистрации событий, таких как существующие сведения о процессах, потоки, изображения, загруженные для каждого процесса, а также конфигурация оборудования, например ЦП, видео, диск, сетевые карты, службы, питание, Plug and Play и каналы интегрированной среды разработки дисков.

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

ERROR_SUCCESS указывает на успех.

Возможные значения ошибок описаны в следующей таблице.

Значение ошибки Описание

ERROR_ALREADY_EXISTS

В системе выполняется только один экземпляр средства ведения журнала ядра. Если эта функция пытается запуститься после того, как другой компонент запустил ведение журнала ядра, возможно, будет возвращена эта ошибка.

ERROR_INVALID_FLAGS

Возможно, указывает на наличие недопустимых флагов трассировки в Properties.EnableFlags.

ERROR_OUT_OF_MEMORY

Возможно, указывает на невозможность выделения памяти для EVENT_TRACE_PROPERTIES.

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

Комментарии

Если StackTracingEventIds содержит события, которые не включены в EVENT_TRACE_PROPERTIES. Поле EnableFlags или не может быть декодировано элементом управления трассировкой ядра, эти флаги игнорируются и код ошибки не возвращается.

Требования.

Версии: Доступно начиная с Windows Vista. Эта структура распределяется с windows Анализатор производительности.

Заголовки: Объявлен в KernelTraceControl.h. Включите KernelTraceControl.h.

Библиотека: Содержится в KernelTraceControl.dll.

Функции

Пользовательское внедрение сведений о системе