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

Структура EVENT_TRACE_PROPERTIES содержит сведения о сеансе трассировки событий. Эта структура используется с ТАКИМИ API, как StartTrace и ControlTrace , при определении, обновлении или запросе свойств сеанса.

Синтаксис

typedef struct _EVENT_TRACE_PROPERTIES {
  WNODE_HEADER Wnode;
  ULONG        BufferSize;
  ULONG        MinimumBuffers;
  ULONG        MaximumBuffers;
  ULONG        MaximumFileSize;
  ULONG        LogFileMode;
  ULONG        FlushTimer;
  ULONG        EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG        NumberOfBuffers;
  ULONG        FreeBuffers;
  ULONG        EventsLost;
  ULONG        BuffersWritten;
  ULONG        LogBuffersLost;
  ULONG        RealTimeBuffersLost;
  HANDLE       LoggerThreadId;
  ULONG        LogFileNameOffset;
  ULONG        LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Члены

Wnode

Структура WNODE_HEADER . Необходимо указать элементы BufferSize, Flags и Guid . При необходимости можно указать элемент ClientContext .

BufferSize

Килобайт памяти, выделенный для каждого буфера сеанса трассировки событий. Минимальный размер буфера составляет 4 (4 КБ). Максимальный размер буфера составляет 16384 (16 МБ). Большинство сеансов трассировки должны использовать буфер размером не более 64 КБ, чтобы избежать нехватки памяти и дискового пространства. До Windows 8: максимальный размер буфера составляет 1024 (1 МБ).

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

• Сеанс с небольшими событиями и низкой частотой событий (несколько КБ/с) должен использовать небольшой размер буфера (от 4 ДО 16 КБ).
• Сеанс с небольшими событиями и умеренной частотой событий должен использовать буфер среднего размера (от 16 ДО 32 КБ).
• Сеанс с большими событиями или высокой частотой событий (несколько МБ/с) должен использовать буфер большого размера (от 64 КБ до 128 КБ).
• В редких случаях, когда для диагностической трассировки необходимо зарезервировать большой объем памяти с сотнями мегабайт данных в секунду, огромный размер буфера (от 256 КБ до 1024 КБ) может снизить нагрузку на ЦП.

Трассировка событий Windows может изменить запрошенный BufferSize в сторону увеличения в определенных сценариях. Например, при записи файла трассировки на диск трассировка трассировки может увеличить размер буфера до кратного размера физического блока диска.

MinimumBuffers

Минимальное количество буферов, зарезервированных для буферного пула сеанса трассировки.

Трассировка событий Windows может изменить это значение в определенных сценариях.

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

Для файловых трассировок и трассировок в режиме реального времени с умеренной частотой событий большинство пользователей должны свести к минимуму использование памяти, задав параметру MinimumBuffers значение 0 или до минимального минимума (например, 4 или 8), позволяя трассировки событий Windows изменять значение вверх в зависимости от количества процессоров. EtW зарезервирует (скорректированное) минимальное количество буферов при запуске трассировки. Если буферы заполняются быстрее, чем их можно обработать, трассировка событий Windows попытается выделить буферы сложения вплоть до числа, указанного Параметром MaximumBuffers.

Для трассировок в режиме буферизации (циклических операций в памяти) пользователи должны задать параметр MinimumBuffers в соответствии с общим объемом памяти, который требуется зарезервировать для сеанса. Обычно это вычисляется на основе ожидаемой частоты событий и времени, в течение которого трассировка должна охватывать. Например, если вы ожидаете скорость передачи данных 16 КБ в секунду и хотите, чтобы трассировка записыла не менее 60 секунд данных, потребуется 960 КБ. Если размер буфера составляет 32 КБ, необходимо задать значение MinimumBuffers равным 30 (всего 960 КБ / 32 КБ на буфер = 30 буферов). EtW зарезервирует (скорректированное) минимальное количество буферов при запуске трассировки. Когда все буферы заполнены, трассировка событий Windows повторно использует самый старый заполненный буфер для новых событий. Обратите внимание, что трассировка событий Windows не выделяет дополнительные буферы (трассировки в режиме буферизации в трассировках трассировки трассировки в режиме буферизации не выделяются трассировками).

MaximumBuffers

Максимальное количество буферов, выделяемых для буферного пула сеанса трассировки.

Трассировка событий Windows может изменить это значение в определенных сценариях.

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

Большинству пользователей следует начать настройку сеанса, установив для параметра MinimumBuffers и MaximumBuffers одинаковое значение. Затем можно увеличить значение MaximumBuffers, если трассировка удаляет события во время пиковых значений частоты событий.

Трассировка событий Windows не может выделить буферы по запросу, если событие создается драйвером с высоким уровнем IRQL. Если сеанс трассировки должен записывать события от поставщиков режима ядра с высоким уровнем IRQL, может потребоваться использовать более высокое значение MinimumBuffers , чтобы принудительно выделить буферы.

MaximumFileSize

Максимальный размер файла, используемого для регистрации событий, в мегабайтах или нуль, если размер не ограничен. Как правило, этот элемент используется для ограничения размера циклического файла журнала, если для параметра LogFileMode задано значение EVENT_TRACE_FILE_MODE_CIRCULAR. Для этого элемента должно быть задано ненулевое значение, если LogFileMode содержит EVENT_TRACE_FILE_MODE_PREALLOCATE, EVENT_TRACE_FILE_MODE_CIRCULAR или EVENT_TRACE_FILE_MODE_NEWFILE.

Если вы используете системный диск (диск, содержащий операционную систему) для ведения журнала, трассировка windows проверяет наличие дополнительных 200 МБ дискового пространства независимо от того, используется ли параметр максимального размера файла. Таким образом, если указать 100 МБ в качестве максимального размера файла трассировки на системном диске, необходимо иметь 300 МБ свободного места на диске.

LogFileMode

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

Трассировка событий Windows буферизует события для сеансов в режиме реального времени, когда для сеанса нет потребителей в режиме реального времени. Обратите внимание, что эта буферизация ограничена. Если ограничение достигнуто, новые события будут игнорироваться, а функции ведения журнала завершаются сбоем с STATUS_LOG_FILE_FULL. До Windows Vista: Если потребитель в режиме реального времени отсутствует, события удаляются, а ведение журнала продолжается.

Не запускайте сеанс ведения журнала в режиме реального времени, если потребитель в режиме реального времени не будет использовать события. Сеанс в режиме реального времени без потребителей будет тратить системные ресурсы (ЦП, память и дисковое пространство для буферизации событий).

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

FlushTimer

Как часто в секундах очищаются все непустые буферы трассировки. Минимальное время очистки — 1 секунда.

• Для сеансов в файловом режиме. Установка значения 0 для FlushTimer отключит очистку на основе времени (очистка будет происходить при заполнении буфера, при остановке сеанса или при явной очистке сеанса). Большинство трассировок в файловом режиме должны устанавливать для FlushTimer значение 0, чтобы избежать пустого места в файле трассировки (т. е. чтобы дисковое пространство не тратилось на хранение в основном пустых буферов). Если есть вероятность того, что трассировка не будет закрыта,может потребоваться задать для таймера ненулевое значение (например, если вы хотите получить события, даже если система аварийно завершает работу).
• Для сеансов в режиме реального времени. Если задать значение 0 для FlushTimer , по умолчанию будет задано время ожидания 1 секунда. Сеансы в режиме реального времени должны задавать таймер очистки в зависимости от того, как быстро должны быть получены данные. Обратите внимание, что более высокое значение таймера снизит нагрузку на ЦП для трассировки. Большинство трассировок в режиме реального времени должны начинаться с таймера 5 или 10 секунд и настраивать таймер в зависимости от необходимости.
• Для буферизованного (циклического в памяти) сеанса FlushTimer не используется. Данные трассировки будут сбрасываться только по запросу (т. е. сбрасываются в файл с помощью ControlTrace).

EnableFlags

Сеанс средства ведения журнала системы может задать EnableFlags , чтобы указать, какие события SystemTraceProvider должны быть включены в трассировку.

Этот элемент может содержать одно или несколько из следующих значений. Помимо указанных событий, если не указано EVENT_TRACE_FLAG_NO_SYSCONFIG, средство ведения журнала также записывает события конфигурации оборудования в Windows XP и события конфигурации системы в Windows Server 2003 или более поздней версии.

• EVENT_TRACE_FLAG_ALPC (0x00100000)

  Включает типы событий ALPC .

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_CSWITCH (0x00000010)

  Включает следующий тип событий Thread :

  • CSwitch

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_DBGPRINT (0x00040000)

  Позволяет преобразовать вызовы DbgPrint и DbgPrintEx в события ETW.

• EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)

  Включает следующий тип события FileIo (необходимо также включить EVENT_TRACE_FLAG_DISK_IO):

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  Включает следующие типы событий DiskIo :

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  Включает следующий тип события DiskIo :

  • DiskIo_TypeGroup2

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  Включает следующий тип событий Thread :

  • ReadyThread

  Это значение поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.

• EVENT_TRACE_FLAG_DPC (0x00000020)

  Включает следующий тип событий PerfInfo :

  • DPC

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  Включает следующие типы событий DiskIo :

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  Включает следующие типы событий FileIo :

  • FileIo_OpEnd

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  Включает следующий тип событий FileIo :

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  Включает следующий тип событий Image :

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  Включает следующий тип событий PerfInfo :

  • ISR

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_JOB (0x00080000)

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

• EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)

  Включает следующий тип события PageFault_V2 :

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  Включает следующий тип события PageFault_V2 :

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)

  Включает типы событий TcpIp и UdpIp .

• EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)

  Не выполняйте очистку конфигурации системы.

  Это значение поддерживается в Windows 8, Windows Server 2012 и более поздних версиях.

• EVENT_TRACE_FLAG_PROCESS (0x00000001)

  Включает следующий тип событий Process :

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  Включает следующий тип события Process_V2 :

  • Process_V2_TypeGroup2

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  Включает следующий тип событий PerfInfo :

  • SampledProfile

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_REGISTRY (0x00020000)

  Включает типы событий реестра .

• EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)

  Включает типы событий SplitIo .

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)

  Включает следующий тип событий PerfInfo :

  • SysCallEnter
  • SysCallExit

  Это значение поддерживается в Windows Vista и более поздних версиях.

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  Включает следующий тип событий Thread :

  • Thread_TypeGroup1

• EVENT_TRACE_FLAG_VAMAP (0x00008000)

  Включает тип событий map и unmap (за исключением файлов изображений).

  Это значение поддерживается в Windows 8, Windows Server 2012 и более поздних версиях.

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)

  Включает следующий тип события PageFault_V2 :

  • PageFault_VirtualAlloc

  Это значение поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.

DUMMYUNIONNAME

DUMMYUNIONNAME.AgeLimit

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

Windows 2000: Задержка времени перед освобождением неиспользуемых буферов в минутах. Значение по умолчанию — 15 минут.

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

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

FreeBuffers

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

EventsLost

В выходных данных — количество событий, которые не были записаны.

BuffersWritten

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

LogBuffersLost

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

RealTimeBuffersLost

На выходных данных — количество буферов, которые не могут быть доставлены потребителю в режиме реального времени.

LoggerThreadId

В выходных данных — идентификатор потока для сеанса трассировки событий.

LogFileNameOffset

Смещение (в байтах) от начала выделенной памяти этой структуры до начала строки, завершаемой nul, содержащей имя файла журнала.

Имя файла обычно имеет .etl расширение. Все папки в пути должны уже существовать (трассировка событий Windows не будет создавать папки). Путь может быть относительным, абсолютным, локальным или удаленным. Переменные среды в пути не будут развернуты. Пользователь должен иметь разрешение на запись в папку.

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

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

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

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

LoggerNameOffset

Смещение (в байтах) от начала выделенной памяти структуры до начала строки с завершением nul, содержащей имя сеанса.

Длина имени сеанса ограничена 1024 символами. Имя сеанса не учитывает регистр. Система не запустит новый сеанс, если уже запущен другой сеанс с тем же именем.

Windows 2000: В именах сеансов учитывается регистр. В результате сеансы с именами, отличающимися только в случае, допускаются. Однако, чтобы избежать путаницы, следует убедиться, что имена сеансов уникальны.

Комментарии

При выделении памяти для этой структуры необходимо выделить достаточно памяти, чтобы включить имя сеанса и имя файла журнала после структуры. Имя сеанса должно находиться перед именем файла журнала в памяти. Необходимо скопировать имя файла журнала в смещение, но не копировать имя сеанса в смещение. Функция StartTrace копирует имя.

Не забудьте инициализировать память для этой структуры до нуля, прежде чем задавать какие-либо члены. Пример:

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

События от поставщиков записываются в буферы сеанса. При заполнении буфера в файле или сеансе в режиме реального времени (или при истечении срока действия FlushTimer) сеанс очищает буфер, записывая события в файл журнала, доставляя их потребителю в режиме реального времени или и то, и другое. Если буферы сеанса заполняются быстрее, чем их можно очистить, новые буферы выделяются и добавляются в буферный пул сеанса вплоть до MaximumBuffers. За пределами этого ограничения сеанс удаляет входящие события до тех пор, пока буфер не станет доступным. В каждом сеансе сохраняется запись о количестве отмененных событий (см. элемент EventsLost ).

Чтобы просмотреть статистику сеанса, например EventsLost во время сеанса, вызовите функцию ControlTrace и задайте для параметра ControlCode значение EVENT_TRACE_CONTROL_QUERY.

Требования

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

StartTrace

ControlTrace

QueryAllTraces

Константы режима ведения журнала

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER