Настройка и запуск сеанса трассировки событий
Чтобы настроить сеанс трассировки событий, используйте структуру EVENT_TRACE_PROPERTIES для указания свойств сеанса. Память, выделенная для структуры EVENT_TRACE_PROPERTIES , должна быть достаточно большой, чтобы также содержать имена сеансов и файлов журнала, которые соответствуют структуре в памяти.
После указания свойств сеанса вызовите функцию StartTrace , чтобы запустить сеанс. Если функция выполнена успешно, параметр SessionHandle будет содержать дескриптор сеанса, а свойство LoggerNameOffset будет содержать смещение к имени сеанса.
Чтобы разрешить поставщикам, от которых вы хотите записывать события в своем сеансе, вызовите функцию EnableTrace для включения классических поставщиков и функцию EnableTraceEx для включения поставщиков на основе манифестов. Чтобы включить поставщикам возможность логирования событий с фильтрацией сеансов по определенным условиям в Windows 8.1, Windows Server 2012 R2 и более поздних версиях, вызовите функцию EnableTraceEx2.
Кроме того, можно также отслеживать дополнительные сведения о событии с помощью вызова функции TraceSetInformation. TraceSetInformation помещает дополнительные сведения трассировки в расширенный раздел данных события и может включать такие сведения, как сведения о версии трассировки или то, какие поставщики в настоящее время зарегистрированы в системе. Для получения дополнительной информации см. Получение дополнительных данных трассировки событий.
До восьми сеансов трассировки могут включать и получать события от одного и того же поставщика на основе манифеста. Однако только один сеанс трассировки может включить классический поставщик. Если несколько сеансов трассировки пытаются включить классического поставщика, первый сеанс перестал бы получать события, когда второй сеанс его включит. Например, если сеанс A включил поставщика 1, а затем сеанс B включил поставщика 1, только сеанс B будет получать события от поставщика 1.
Вы можете использовать любую из трех функций для включения поставщика, но вы можете потерять функциональные возможности, если вы используете EnableTrace для включения поставщика на основе манифеста, так как вы не сможете предоставить значение MatchAllKeyword, указать расширенные элементы данных для включения в событие или предоставить данные фильтра, определяемые поставщиком. Дополнительные сведения см. в разделе "Примечания" каждой функции.
В Windows 8.1, Windows Server 2012 R2 и более поздних версиях данные полезной нагрузки события, области фильтров и обхода стека можно использовать в функции EnableTraceEx2 и с помощью структур ENABLE_TRACE_PARAMETERS и EVENT_FILTER_DESCRIPTOR для фильтрации на основании определенных условий в сеансе ведения журнала. Дополнительные сведения о фильтрах полезных данных событий см. в функциях TdhCreatePayloadFilter и TdhAggregatePayloadFilters, а также в структурах ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR и PAYLOAD_FILTER_PREDICATE.
Чтобы определить уровень и ключевые слова, используемые для включения поставщика, основанного на манифесте, используйте одну из следующих команд:
- Logmanзапросимя-поставщика
- Wevtutilgpprovider-name
Команды перечисляют только уровень и ключевые слова, поставщик должен документирует все требования к данным фильтра для потенциальных контроллеров.
Для перечисления поставщиков на основе манифеста используйте Wevtutilep.
Для классических поставщиков именно от них зависит документирование и предоставление доступа потенциальным контроллерам к уровням серьезности или флагам включения, которые они поддерживают. Если поставщик хочет быть включенным любым контроллером, он должен принять 0 как для уровня серьезности, так и для флагов включения, и интерпретировать 0 как запрос на выполнение ведения журнала по умолчанию (каким бы оно ни было).
Вы можете включить поставщика до или после его регистрации. После включения поставщика ETW вызовет функцию обратного вызова поставщика. Если поставщик не зарегистрирован, ETW вызовет функцию обратного вызова поставщика после регистрации.
Вы также можете использовать функцию EnableTrace, чтобы отключить поставщика (остановить ведение журнала в вашем сеансе) или обновить уровень логирования или включить флаги для поставщика. С помощью функции EnableTraceEx можно отключить поставщик или обновить уровень, ключевые слова, расширенные данные и фильтровать данные. При каждом вызове функции EnableTrace или EnableTraceEx, ETW вызывает функцию обратного вызова поставщика. Поставщик остаётся включённым для сеанса до тех пор, пока сеанс не отключит его.
Чтобы остановить сеанс трассировки после сбора событий, вызовите функцию ControlTrace и передайте EVENT_TRACE_CONTROL_STOP в качестве кода элемента управления. Чтобы указать сеанс для остановки, можно передать дескриптор сеанса трассировки событий, полученный из предыдущего вызова функции StartTrace , или имя ранее запущенного сеанса. Не забудьте отключить всех поставщиков перед остановкой сеанса. Если вы остановите сеанс, не отключив сначала поставщика, ETW отключит поставщика и попытается вызвать его контрольную функцию обратного вызова. Если приложение, запущенное сеансом, завершается без отключения поставщика или вызова функции ControlTrace , поставщик по-прежнему включен.
Если ControlTrace выполнен успешно, свойства сеанса обновляются, чтобы отразить окончательные значения свойств и выполнить статистику для сеанса трассировки событий.
Пример запуска сеанса трассировки событий см. в следующем примере:
- Пример создания сеанса и включения поставщика на основе манифеста— запускает сеанс трассировки, включает поставщика на основе манифеста, отключает поставщика, а затем останавливает сеанс.
Дополнительные сведения о запуске сеанса трассировки см. в следующем разделе:
- Настройка и запуск сеанса SystemTraceProvider
- Настройка и запуск сеанса ведения журнала ядра NT
- Настройка и запуск сеанса AutoLogger
- Настройка и запуск сеанса глобального средства ведения журнала
- Настройка и запуск сеанса частного ведения журнала
Связанные темы