функция обратного вызова PEVENT_RECORD_CALLBACK (evntrace.h)

Статья
03/11/2023

Потребители реализуют этот обратный вызов для получения событий из сеанса обработки трассировки.

Тип PEVENT_RECORD_CALLBACK определяет указатель на эту функцию обратного вызова. EventRecordCallback — это заполнитель для имени функции, определяемой приложением.

Синтаксис

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

Параметры

[in] EventRecord

Указатель на структуру EVENT_RECORD , содержащую сведения о событии.

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

None

Remarks

Чтобы указать функцию, вызываемую трассировой событий Windows для доставки событий, задайте элементы EventRecordCallback, Context и ProcessTraceModeструктуры EVENT_TRACE_LOGFILE , передаваемой в функцию OpenTrace .

Задайте для свойства EventRecordCallback адрес функции обратного вызова.
Задайте для контекста значение, которое должно быть включено в поле UserContext каждого EVENT_RECORD , предоставленного для обратного вызова.
Задайте для Параметра ProcessTraceMode флаги, которые будут использоваться при обработке трассировки. Чтобы использовать Функцию EventRecordCallback, необходимо включить PROCESS_TRACE_MODE_EVENT_RECORD в значение ProcessTraceMode .

Примечание

Если функция EventRecordCallback получает искаженные данные из ProcessTrace, дважды проверка флаги, указанные в ProcessTraceMode поле структуры, предоставленной EVENT_TRACE_LOGFILEв OpenTrace. EVENT_TRACE_LOGFILEПоля EventCallback и EventRecordCallback являются перекрывающимися членами объединения. Если поле ProcessTraceMode содержит PROCESS_TRACE_MODE_EVENT_RECORD флаг , ProcessTrace вызовет обратный вызов с помощью сигнатуры функции EventRecordCallback . В противном случае ProcessTrace вызовет обратный вызов с помощью сигнатуры функции EventCallback .

После использования OpenTrace для создания сеанса обработки трассировки вызовите функцию ProcessTrace , чтобы начать получать события.

Когда ProcessTrace начинает обработку событий из трассировки, он может вызывать обратный вызов с одним или несколькими искусственными событиями, содержащими данные о трассировке (метаданные), а не данные из зарегистрированных событий. Для этих искусственных событий задано значение EventTraceGuidEventHeader.ProviderId и EventHeader.EventDescriptor.Opcode на основе содержимого искусственного события. Например, первое событие из каждого файла трассировки будет искусственным событием с opcode 0, содержащим TRACE_LOGFILE_HEADER сведения.

Все остальные получаемые события содержат данные о событиях, зависящих от поставщика. Чтобы определить тип полученного события, используйте элементы EventHeader.ProviderId и EventHeader.EventDescriptorEVENT_RECORD .

Если событие поступает от известного поставщика и вы знаете структуру данных, вы можете использовать собственную систему для декодирования событий.
Если поле EventHeader.Flags содержит EVENT_HEADER_FLAG_TRACE_MESSAGE флаг , событие является сообщением WPP. Если доступны соответствующие сведения о декодирования (TMF или PDB-файл), событие можно декодировать с помощью TdhGetProperty или TdhGetWppProperty.
В противном случае событие может быть событием на основе MOF, на основе манифеста или TraceLogging. Если доступны соответствующие сведения о декодирования, событие можно декодировать с помощью TdhGetEventInformation.
- Если событие использует декодирование на основе MOF, TdhGetEventInformation будет искать сведения о декодировании событий в хранилище данных WMI системы.
- Если событие использует декодирование на основе манифеста, TdhGetEventInformation будет искать сведения о декодирования событий в зарегистрированных манифестах системы или в манифестах или двоичных файлах, загруженных в контекст декодирования для каждого процесса TdhLoadManifest или TdhLoadManifestFromBinary.
- Если событие использует декодирование на основе TraceLogging, TdhGetEventInformation будет использовать декодированные данные из события.

В большинстве случаев события будут доставляться в обратный вызов в том порядке, в котором они произошли (порядок меток времени). Однако в некоторых случаях события могут быть доставлены не в исходном порядке.

Если трассировка использует системное время для метки времени сеанса (т. е. сеанс трассировки был запущен с properties.Wnode.ClientContext значением 2), а системные часы корректируются назад, пока сеанс собирает события, некоторые события могут быть доставлены не по порядку. Чтобы избежать этого, установите для параметра ClientContext значение 0, чтобы получить метку времени по умолчанию (время QPC).
Если трассировка собирается с помощью меток времени из неточные часы, события с одной и той же меткой времени из разных ЦП могут доставляться не по порядку. Чаще всего это происходит, когда трассировка использует системное время для метки времени сеанса, так как системное время тактов. Эту проблему можно избежать, запустив сеанс с EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING помощью флагов LogFileMode , хотя это может оказать существенное негативное влияние на производительность трассировки. Начиная с Windows 10: Тип системных часов времени использует GetSystemTimePreciseAsFileTime для снижения вероятности возникновения этой проблемы.
Если трассировка повреждена, была создана с помощью низкоуровневых API, которые не поддерживают ожидаемые правила меток времени в файле или используют параметры переопределения меток времени при записи событий, некоторые события могут быть доставлены не по порядку.

Технические сведения: События хранятся в буферах. Каждый буфер назначается потоку буфера, обычно по одному потоку для каждого ЦП. Реализация ProcessTrace предполагает, что все события в буфере сортируются по метке времени и что каждый буфер содержит события за один промежуток времени, который не перекрывает диапазон любого другого буфера в потоке этого буфера. Если эти предположения не выполняются, ProcessTraceможет доставлять события не по порядку.

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

Важно!

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

Дополнительные сведения о интерпретации данных события см. в разделах Использование событий и Получение данных событий с помощью TDH.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	evntrace.h