PEVENT_RECORD_CALLBACK Rückruffunktion (evntrace.h)

Artikel
03/11/2023

Consumer implementieren diesen Rückruf, um Ereignisse von einer Ablaufverfolgungsverarbeitungssitzung zu empfangen.

Der PEVENT_RECORD_CALLBACK Typ definiert einen Zeiger auf diese Rückruffunktion. EventRecordCallback ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Syntax

PEVENT_RECORD_CALLBACK PeventRecordCallback;

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

Parameter

[in] EventRecord

Zeiger auf eine EVENT_RECORD-Struktur , die die Ereignisinformationen enthält.

Rückgabewert

Keine

Bemerkungen

Um die Funktion anzugeben, die ETW aufruft, um Ereignisse zu übermitteln, legen Sie die Member EventRecordCallback, Context und ProcessTraceMode der EVENT_TRACE_LOGFILE-Struktur fest, die Sie an die OpenTrace-Funktion übergeben.

Legen Sie EventRecordCallback auf die Adresse Ihrer Rückruffunktion fest.
Legen Sie Context auf einen Wert fest, der im Feld UserContext der einzelnen EVENT_RECORD enthalten sein soll, die für Den Rückruf bereitgestellt werden.
Legen Sie ProcessTraceMode auf die Flags fest, die bei der Verarbeitung der Ablaufverfolgung verwendet werden sollen. Um EventRecordCallback verwenden zu können, müssen Sie PROCESS_TRACE_MODE_EVENT_RECORD in den ProcessTraceMode-Wert einschließen.

Hinweis

Wenn Ihre EventRecordCallback-Funktion unzutreffende Daten von ProcessTrace empfängt, überprüfen Sie die Flags, die ProcessTraceMode im Feld der EVENT_TRACE_LOGFILE Für OpenTrace bereitgestellten Struktur angegeben sind. EVENT_TRACE_LOGFILEDie Felder EventCallback und EventRecordCallback sind überlappende Elemente einer Union. Wenn das ProcessTraceMode Feld das PROCESS_TRACE_MODE_EVENT_RECORD Flag enthält, ruft ProcessTrace Ihren Rückruf mithilfe der EventRecordCallback-Funktionssignatur auf. Andernfalls ruft ProcessTrace Ihren Rückruf mithilfe der EventCallback-Funktionssignatur auf.

Nachdem Sie OpenTrace zum Erstellen der Ablaufverfolgungsverarbeitungssitzung verwendet haben, rufen Sie die ProcessTrace-Funktion auf, um mit dem Empfang der Ereignisse zu beginnen.

Wenn ProcessTrace mit der Verarbeitung von Ereignissen aus einer Ablaufverfolgung beginnt, kann ihr Rückruf mit einem oder mehreren synthetischen Ereignissen aufgerufen werden, die Daten zur Ablaufverfolgung (Metadaten) anstelle von Daten aus protokollierten Ereignissen enthalten. Für diese synthetischen Ereignisse ist EventHeader.ProviderId auf EventTraceGuid und eventHeader.EventDescriptor.Opcode basierend auf dem Inhalt des synthetischen Ereignisses festgelegt. Beispielsweise ist das erste Ereignis aus jeder Ablaufverfolgungsdatei ein synthetisches Ereignis mit Opcode 0, das TRACE_LOGFILE_HEADER Informationen enthält.

Alle anderen Ereignisse, die Sie erhalten, enthalten anbieterspezifische Ereignisdaten. Sie verwenden die Member EventHeader.ProviderId und EventHeader.EventDescriptor von EVENT_RECORD , um den Typ des empfangenen Ereignisses zu bestimmen.

Wenn das Ereignis von einem bekannten Anbieter stammt und Sie das Layout der Daten kennen, können Sie ihr eigenes System zum Decodieren der Ereignisse verwenden.
Wenn das Feld EventHeader.Flags das EVENT_HEADER_FLAG_TRACE_MESSAGE Flag enthält, ist das Ereignis eine WPP-Nachricht. Wenn die entsprechenden Decodierungsinformationen (TMF- oder PDB-Datei) verfügbar sind, kann das Ereignis mit TdhGetProperty oder TdhGetWppProperty decodiert werden.
Andernfalls kann es sich bei dem Ereignis um ein MOF-basiertes, manifestbasiertes oder TraceLogging-Ereignis handeln. Wenn die entsprechenden Decodierungsinformationen verfügbar sind, kann das Ereignis mit TdhGetEventInformation decodiert werden.
- Wenn das Ereignis die MOF-basierte Decodierung verwendet, sucht TdhGetEventInformation im WMI-Datenspeicher des Systems nach Ereignisdecodierungsinformationen.
- Wenn das Ereignis manifestbasierte Decodierung verwendet, sucht TdhGetEventInformation nach Ereignisdecodierungsinformationen in den registrierten Manifesten des Systems oder in Manifesten oder Binärdateien, die von TdhLoadManifest oder TdhLoadManifestFromBinary in den Prozessdecodierungskontext geladen werden.
- Wenn das Ereignis die TraceLogging-basierte Decodierung verwendet, verwendet TdhGetEventInformation die Decodierungsinformationen aus dem Ereignis.

In den meisten Fällen werden Ereignisse an Ihren Rückruf in der Reihenfolge übermittelt, in der sie aufgetreten sind (Zeitstempelreihenfolge). Unter bestimmten Umständen werden die Ereignisse jedoch möglicherweise nicht in ihrer ursprünglichen Bestellung geliefert.

Wenn die Ablaufverfolgung die Systemzeit für den Sitzungszeitstempel verwendet (d. h. die Ablaufverfolgungssitzung wurde mit properties.Wnode.ClientContext festgelegt auf 2 gestartet) und die Systemuhr rückwärts angepasst wird, während die Sitzung Ereignisse erfasst, werden einige der Ereignisse möglicherweise nicht ordnungsgemäß übermittelt. Um dies zu vermeiden, legen Sie ClientContext auf 0 fest, um den Standardzeitstempel (QPC-Zeit) abzurufen.
Wenn die Ablaufverfolgung mithilfe von Zeitstempeln von einer ungenauen Uhr erfasst wird, können Ereignisse mit demselben Zeitstempel von verschiedenen CPUs außerhalb der Reihenfolge übermittelt werden. Dies tritt am häufigsten auf, wenn die Ablaufverfolgung Systemzeit für den Sitzungszeitstempel verwendet, da die Systemzeit tickt. Dieses Problem kann vermieden werden, indem die Sitzung mit EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING in den LogFileMode-Flags gestartet wird, obwohl dies erhebliche negative Auswirkungen auf die Ablaufverfolgungsleistung haben kann. Ab Windows 10: Der Systemzeituhrtyp verwendet GetSystemTimePreciseAsFileTime, um die Wahrscheinlichkeit dieses Problems zu verringern.
Wenn die Ablaufverfolgung beschädigt ist, mithilfe von APIs auf niedriger Ebene generiert wurde, die nicht die erwarteten Zeitstempelregeln in der Datei beibehalten, oder wenn beim Schreiben von Ereignissen Optionen für die Zeitstempelüberschreibung verwendet werden, werden einige der Ereignisse möglicherweise nicht ordnungsgemäß übermittelt.

Technische Details: Ereignisse werden in Puffern gespeichert. Jeder Puffer wird einem Pufferdatenstrom zugewiesen, in der Regel ein Datenstrom für jede CPU. Bei der ProcessTrace-Implementierung wird davon ausgegangen, dass alle Ereignisse in einem Puffer nach Zeitstempel sortiert sind und dass jeder Puffer Ereignisse für eine einzelne Zeitspanne enthält, die die Spanne eines anderen Puffers im Datenstrom dieses Puffers nicht überschneidet. Wenn diese Annahmen nicht erfüllt sind, liefert ProcessTracemöglicherweise Ereignisse außerhalb der Reihenfolge.

Wenn eine Echtzeit-Ablaufverfolgungssammlungssitzung keine zugeordneten Ablaufverfolgungsverarbeitungssitzungen enthält, werden gesammelte Ereignisse vom System gepuffert, bis der Puffer voll ist. Wenn eine Ablaufverfolgungsverarbeitungssitzung eine Verbindung mit einer Echtzeit-Ablaufverfolgungssammlungssitzung herstellt, empfängt die Ablaufverfolgungsverarbeitungssitzung die synthetischen Ereignisse für die Sitzung, dann die gepufferten Ereignisse und empfängt dann die neu generierten Echtzeitereignisse. Wenn eine zweite Echtzeitverarbeitungssitzung eine Verbindung mit derselben Ablaufverfolgungssammlungssitzung herstellt, empfängt sie die synthetischen Ereignisse und die neu generierten Echtzeitereignisse (die zweite Ablaufverfolgungsverarbeitungssitzung empfängt keine älteren Ereignisse).

Wichtig

Wenn bei der Verarbeitung von Ereignissen aus einer Echtzeitsitzung der Verarbeitungsrückruf zu viel Zeit für die Verarbeitung jedes Ereignisses benötigt wird und Ereignisse zu schnell eintreffen, wird er ins Hintertreffen geraten. Das System puffert Ereignisse, um Datenverluste zu verhindern, aber dies erhöht die Systemressourcenauslastung (z. B. Arbeitsspeicher- und Datenträgerauslastung). Vermeiden Sie dieses Problem, indem Sie Sitzungsfilter (z. B. Ebenen- und Schlüsselwort (keyword)filter für jeden Anbieter) verwenden, um die Rate der eingehenden Ereignisse zu reduzieren, indem Sie ihren Rückruf frühzeitig filtern, um Ereignisse zu überspringen, die keine vollständige Verarbeitung erfordern, und den Rückruf so optimieren, dass er so schnell wie möglich zurückgegeben wird, um eine Blockierung des Verarbeitungsthreads zu vermeiden.

Weitere Informationen zum Interpretieren der Ereignisdaten finden Sie unter Verwenden von Ereignissen und Abrufen von Ereignisdaten mithilfe von TDH.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	evntrace.h