структура EVENT_TRACE_PROPERTIES (evntrace.h)
Структура EVENT_TRACE_PROPERTIES содержит сведения о сеансе трассировки событий. Эта структура используется с ТАКИМИ API, как StartTrace и ControlTrace , при определении, обновлении или запросе свойств сеанса.
Примечание
Это структура версии 1. Дополнительные параметры поддерживаются EVENT_TRACE_PROPERTIES_V2 (например , FilterDesc и V2Options).
Синтаксис
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 не может собирать события размером более 64 КБ.
Трассировка событий Windows может изменить запрошенный BufferSize в сторону увеличения в определенных сценариях. Например, при записи файла трассировки на диск трассировка трассировки может увеличить размер буфера до кратного размера физического блока диска.
Важно!
BufferSize является одним из наиболее важных параметров для сеанса трассировки. Большие буферы обычно тратят память и дисковое пространство. Сеансы трассировки с большими буферами (256 КБ или больше) следует использовать только для диагностических исследований или тестирования, а не для трассировки в рабочей среде.
Совет
Не используйте BufferSize для управления использованием памяти сеанса трассировки. Вместо этого выберите размер буфера в зависимости от размера события сеанса и частоты событий, а затем используйте параметры MinimumBuffers и MaximumBuffers , чтобы настроить использование памяти сеанса.
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 , чтобы принудительно выделить буферы.
Примечание
EtW игнорирует MaximumBuffers для сеансов в режиме буферизации (сеансы, включающие режим EVENT_TRACE_BUFFERING_MODEведения журнала ). Сеансы режима буферизации всегда выделяют 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 должны быть включены в трассировку.
Примечание
EnableFlags действителен только для системных средств ведения журнала, т. е. для сеансов трассировки, которые запускаются с помощью EVENT_TRACE_SYSTEM_LOGGER_MODE флага режима ведения журнала, KERNEL_LOGGER_NAME имени сеанса, идентификатора SystemTraceControlGuid GUID сеанса или идентификатора GUID сеанса GlobalLoggerGuid .
Этот элемент может содержать одно или несколько из следующих значений. Помимо указанных событий, если не указано EVENT_TRACE_FLAG_NO_SYSCONFIG, средство ведения журнала также записывает события конфигурации оборудования в Windows XP и события конфигурации системы в Windows Server 2003 или более поздней версии.
EVENT_TRACE_FLAG_ALPC (0x00100000)
Включает типы событий ALPC .
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_CSWITCH (0x00000010)
Включает следующий тип событий Thread :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_DBGPRINT (0x00040000)
Позволяет преобразовать вызовы DbgPrint и DbgPrintEx в события ETW.
EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)
Включает следующий тип события FileIo (необходимо также включить EVENT_TRACE_FLAG_DISK_IO):
EVENT_TRACE_FLAG_DISK_IO (0x00000100)
Включает следующие типы событий DiskIo :
EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)
Включает следующий тип события DiskIo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_DISPATCHER (0x00000800)
Включает следующий тип событий Thread :
Это значение поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.
EVENT_TRACE_FLAG_DPC (0x00000020)
Включает следующий тип событий PerfInfo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_DRIVER (0x00800000)
Включает следующие типы событий DiskIo :
- DriverCompleteRequest
- DriverCompleteRequestReturn
- DriverCompletionRoutine
- DriverMajorFunctionCall
- DriverMajorFunctionReturn
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_FILE_IO (0x02000000)
Включает следующие типы событий FileIo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)
Включает следующий тип событий FileIo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)
Включает следующий тип событий Image :
EVENT_TRACE_FLAG_INTERRUPT (0x00000040)
Включает следующий тип событий PerfInfo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_JOB (0x00080000)
Это значение поддерживается в Windows 10
EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)
Включает следующий тип события PageFault_V2 :
EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)
Включает следующий тип события PageFault_V2 :
EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)
EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)
Не выполняйте очистку конфигурации системы.
Это значение поддерживается в Windows 8, Windows Server 2012 и более поздних версиях.
EVENT_TRACE_FLAG_PROCESS (0x00000001)
Включает следующий тип событий Process :
EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)
Включает следующий тип события Process_V2 :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_PROFILE (0x01000000)
Включает следующий тип событий PerfInfo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_REGISTRY (0x00020000)
Включает типы событий реестра .
EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)
Включает типы событий SplitIo .
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)
Включает следующий тип событий PerfInfo :
Это значение поддерживается в Windows Vista и более поздних версиях.
EVENT_TRACE_FLAG_THREAD (0x00000002)
Включает следующий тип событий Thread :
EVENT_TRACE_FLAG_VAMAP (0x00008000)
Включает тип событий map и unmap (за исключением файлов изображений).
Это значение поддерживается в Windows 8, Windows Server 2012 и более поздних версиях.
EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)
Включает следующий тип события PageFault_V2 :
Это значение поддерживается в 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, содержащей имя сеанса.
Важно!
Используйте описательное имя сеанса, чтобы его владение и использование можно было определить по имени сеанса. Не используйте GUID или другое неописуемое значение. Не добавляйте случайные цифры, чтобы сделать имя сеанса уникальным. Сеансы трассировки событий Windows — это ограниченный ресурс, поэтому компонент не должен запускать несколько сеансов. Если сеанс компонента уже запущен при запуске компонента, компонент должен очистить потерянный сеанс, а не создавать второй сеанс.
Длина имени сеанса ограничена 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.
Требования
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Верхняя часть | evntrace.h |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по