структура EVENT_TRACE_LOGFILEA (evntrace.h)

Статья
08/23/2023

В структуре EVENT_TRACE_LOGFILE хранятся сведения об источнике данных трассировки.

Структура EVENT_TRACE_LOGFILE используется при вызове OpenTrace. Пользователь предоставляет EVENT_TRACE_LOGFILE структуру со сведениями об источнике данных трассировки (имя ETL-файла или имя активного сеанса средства ведения журнала в режиме реального времени), флагами обработки трассировки и функциями обратного вызова, которые будут получать данные трассировки. При успешном выполнении OpenTrace заполняет оставшиеся поля структуры для возврата сведений об источнике данных трассировки.

Когда ProcessTrace обрабатывает буфер, он вызывает определяемый пользователем BufferCallback с EVENT_TRACE_LOGFILE структурой для предоставления сведений о сеансе обработки событий и буфере.

Синтаксис

typedef struct _EVENT_TRACE_LOGFILEA {
  LPSTR                         LogFileName;
  LPSTR                         LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;

Члены

LogFileName

Имя обрабатываемого файла журнала или ЗНАЧЕНИЕ NULL , если обработка данных из сеанса трассировки в режиме реального времени. Укажите значение для этого элемента, если вы вызываете OpenTrace для использования данных из файла журнала.

Если при вызове OpenTraceимя_журнала не равно NULL , то logFileName должно иметь значение NULL.

При вызове OpenTrace пользователь, потребляющий события, должен иметь разрешения на чтение файла.

Примечание

Имя файла, предоставленное в OpenTrace через поле LogFileName , должно быть полным именем файла, включая все суффиксы. Некоторые API создания файла трассировки могут автоматически добавлять суффикс к указанному пользователем имени файла. Например, если контроллер регистрировал события в закрытом сеансе (контроллер задал элементу LogFileModeEVENT_TRACE_PROPERTIESзначение EVENT_TRACE_PRIVATE_LOGGER_MODE при вызове StartTrace), созданный ETL-файл будет содержать суффикс идентификатора процесса, например mytrace.etl_123. Это также может произойти, если файл был создан в режиме EVENT_TRACE_FILE_MODE_NEWFILE . В этом случае созданный ETL-файл будет содержать порядковый номер.

LoggerName

Имя сеанса трассировки событий в режиме реального времени или ЗНАЧЕНИЕ NULL при обработке данных из файла журнала. Укажите значение для этого элемента, если вы вызываете OpenTrace для использования данных из сеанса в режиме реального времени.

Если при вызове OpenTraceLogFileName имеет значение, отличное от NULL , loggerName должно иметь значение NULL.

События можно использовать только в режиме реального времени, если контроллер трассировки задал элемент LogFileModeEVENT_TRACE_PROPERTIES для включения флага EVENT_TRACE_REAL_TIME_MODE .

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

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

CurrentTime

На выходных данных текущее время в 100-наносекундных интервалах с полуночи 1 января 1601 года.

BuffersRead

На выходе — количество обработанных буферов.

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

Зарезервировано. Не используется.

DUMMYUNIONNAME.ProcessTraceMode

Режимы обработки событий. Режимы определяются в файле заголовка evntcons.h . Можно указать один или несколько следующих режимов:

PROCESS_TRACE_MODE_EVENT_RECORD

Укажите этот режим, если вы хотите получать события в новом формате EVENT_RECORD (настоятельно рекомендуется). Для получения событий в новом формате необходимо указать обратный вызов в элементе EventRecordCallback . Если этот режим не указан, события будут получаться в старом формате через обратный вызов, указанный в элементе EventCallback .

До Windows Vista: Не поддерживается.
PROCESS_TRACE_MODE_RAW_TIMESTAMP

По умолчанию ProcessTrace преобразует метку времени события из исходного необработанного формата (системное время, время QPC или счетчик циклов ЦП) в системное время (100-наносекундные интервалы с полуночи 1 января 1601 г.).

Укажите флаг PROCESS_TRACE_MODE_RAW_TIMESTAMP , если вы не хотите, чтобы значение метки времени в элементе TimeStampэлемента EVENT_HEADER и EVENT_TRACE_HEADER преобразовано в системное время. Если этот флаг указан, ProcessTrace оставит значение метки времени в исходном формате, указанном контроллером в элементе Wnode.ClientContextEVENT_TRACE_PROPERTIES.

До Windows Vista: Не поддерживается.
PROCESS_TRACE_MODE_REAL_TIME

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

CurrentEvent

В выходных данных EVENT_TRACE структура, содержащая последнее обработанное событие.

LogfileHeader

В выходных данных TRACE_LOGFILE_HEADER структуру, содержащую общие сведения о сеансе и компьютере, на котором выполнялся сеанс.

BufferCallback

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

BufferSize

В выходных данных содержит размер каждого буфера в байтах.

Filled

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

EventsLost

Не используется.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

Указатель на функцию EventCallback , которая вызывает etw для каждого события в буфере. Это поле используется только в том случае, если поле ProcessTraceMode не содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг .

Примечание

Поле EventCallback будет рассматриваться как EventRecordCallback , если поле ProcessTraceMode содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг . Если eventCallback получает искаженные данные из ProcessTrace, убедитесь, что поле ProcessTraceMode не содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг .

Совет

Новый код должен использовать EventRecordCallback вместо EventCallback. EventRecordCallback получает EVENT_RECORD который содержит более полную информацию о событии, может использоваться с api-интерфейсами декодирования, такими как TdhGetEventInformation, и имеет указатель контекста, который может использоваться при обратном вызове.

DUMMYUNIONNAME2.EventRecordCallback

Указатель на функцию EventRecordCallback , которая вызывает etw для каждого события в буфере. Это поле используется только в том случае, если поле ProcessTraceMode содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг .

Примечание

Поле EventRecordCallback будет рассматриваться как EventCallback , если поле ProcessTraceMode не содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг . Если eventRecordCallback получает искаженные данные из ProcessTrace, убедитесь, что поле ProcessTraceMode содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг .

До Windows Vista: Не поддерживается.

IsKernelTrace

В выходных данных, если этот элемент имеет значение TRUE, сеанс трассировки событий — это средство ведения журнала ядра NT. В противном случае это другой сеанс трассировки событий.

Context

Контекстные данные, которые потребитель может указать при вызове OpenTrace. Если потребитель использует EventRecordCallback для использования событий, трассировка событий Windows устанавливает для элемента UserContextструктуры EVENT_RECORD это значение.

До Windows Vista: Не поддерживается.

Инициализируйте память для этой структуры до нуля.
При чтении из ETL-файла задайте для параметра LogFileName путь к файлу. В противном случае (т. е. при чтении из сеанса в режиме реального времени) задайте для параметра LoggerName имя сеанса, а для параметра ProcessTraceMode — значение PROCESS_TRACE_MODE_REAL_TIME.
При использовании Функции EventRecordCallback (рекомендуется) задайте для параметра EventRecordCallback адрес функции обратного вызова записи события, задайте для параметра Context значение, которое будет предоставлено обратному вызову, и добавьте PROCESS_TRACE_MODE_EVENT_RECORD в ProcessTraceMode. В противном случае (т. е. при использовании EventCallback) задайте для параметра EventCallback адрес функции обратного вызова события.
Если вам нужен обратный вызов после обработки каждого буфера, задайте для bufferCallback адрес функции обратного вызова буфера.
Если вам нужны исходные необработанные данные метки времени вместо обработанной метки времени, добавьте PROCESS_TRACE_MODE_RAW_TIMESTAMP в ProcessTraceMode.
Вызовите OpenTrace. Обратите внимание, что в случае успешного выполнения функция OpenTrace заполняет элементы этой структуры сведениями из источника данных трассировки.
Вызовите ProcessTrace с дескриптором, возвращенным OpenTrace.
- ProcessTrace вызовет функцию обратного вызова события для каждого события.
- ProcessTrace вызовет функцию обратного вызова буфера (если она указана) после завершения каждого буфера и будет включать экземпляр структуры EVENT_TRACE_LOGFILE со сведениями о состоянии обработки трассировки.
После завершения обработки трассировки вызовите CloseTrace , чтобы закрыть дескриптор, возвращенный OpenTrace.

Примечание

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

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхняя часть	evntrace.h

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

BufferCallback

EventRecordCallback

OpenTrace

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

структура EVENT_TRACE_LOGFILEA (evntrace.h)

Синтаксис

Члены

Комментарии

Требования

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

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

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

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