PEVENT_RECORD_CALLBACK fonction de rappel (evntrace.h)

Article
03/11/2023

Les consommateurs implémentent ce rappel pour recevoir les événements d’une session de traitement de trace.

Le type PEVENT_RECORD_CALLBACK définit un pointeur vers cette fonction de rappel. EventRecordCallback est un espace réservé pour le nom de fonction défini par l’application.

Syntaxe

PEVENT_RECORD_CALLBACK PeventRecordCallback;

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

Paramètres

[in] EventRecord

Pointeur vers une structure EVENT_RECORD qui contient les informations d’événement.

Valeur de retour

None

Notes

Pour spécifier la fonction qu’ETW appelle pour remettre des événements, définissez les membres EventRecordCallback, Context et ProcessTraceMode de la structure EVENT_TRACE_LOGFILE que vous passez à la fonction OpenTrace .

Définissez EventRecordCallback sur l’adresse de votre fonction de rappel.
Définissez Contexte sur une valeur qui doit être incluse dans le champ UserContext de chaque EVENT_RECORD fourni à votre rappel.
Définissez ProcessTraceMode sur les indicateurs à utiliser lors du traitement de la trace. Pour utiliser EventRecordCallback, vous devez inclure PROCESS_TRACE_MODE_EVENT_RECORD dans la valeur ProcessTraceMode .

Notes

Si votre fonction EventRecordCallback reçoit des données brouchées de ProcessTrace, case activée les indicateurs spécifiés dans le ProcessTraceMode champ de la EVENT_TRACE_LOGFILE structure fournie à OpenTrace. EVENT_TRACE_LOGFILEles champs EventCallback et EventRecordCallback sont des membres qui se chevauchent d’une union. Si le ProcessTraceMode champ inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD , ProcessTrace appelle votre rappel à l’aide de la signature de la fonction EventRecordCallback . Sinon, ProcessTrace appelle votre rappel à l’aide de la signature de la fonction EventCallback .

Après avoir utilisé OpenTrace pour créer la session de traitement des traces, appelez la fonction ProcessTrace pour commencer à recevoir les événements.

Lorsque ProcessTrace commence à traiter des événements à partir d’une trace, il peut appeler votre rappel avec un ou plusieurs événements synthétiques qui contiennent des données sur la trace (métadonnées) plutôt que des données provenant d’événements enregistrés. Ces événements synthétiques ont EventHeader.ProviderId défini EventTraceGuid sur et EventHeader.EventDescriptor.Opcode défini en fonction du contenu de l’événement synthétique. Par exemple, le premier événement de chaque fichier de trace sera un événement synthétique avec Opcode 0 contenant TRACE_LOGFILE_HEADER informations.

Tous les autres événements que vous recevez contiennent des données d’événement spécifiques au fournisseur. Vous utilisez les membres EventHeader.ProviderId et EventHeader.EventDescriptor de EVENT_RECORD pour déterminer le type d’événement que vous avez reçu.

Si l’événement provient d’un fournisseur connu et que vous connaissez la disposition des données, vous pouvez utiliser votre propre système pour décoder les événements.
Si le champ EventHeader.Flags inclut l’indicateur EVENT_HEADER_FLAG_TRACE_MESSAGE , l’événement est un message WPP. Si les informations de décodage appropriées (fichier TMF ou PDB) sont disponibles, l’événement peut être décodé à l’aide de TdhGetProperty ou de TdhGetWppProperty.
Sinon, l’événement peut être un événement MOF, basé sur un manifeste ou TraceLogging. Si les informations de décodage appropriées sont disponibles, l’événement peut être décodé à l’aide de TdhGetEventInformation.
- Si l’événement utilise le décodage basé sur MOF, TdhGetEventInformation recherche les informations de décodage d’événement dans le magasin de données WMI du système.
- Si l’événement utilise le décodage basé sur un manifeste, TdhGetEventInformation recherche les informations de décodage d’événement dans les manifestes inscrits du système ou dans les manifestes ou fichiers binaires chargés dans le contexte de décodage par processus par TdhLoadManifest ou TdhLoadManifestFromBinary.
- Si l’événement utilise le décodage basé sur TraceLogging, TdhGetEventInformation utilisera les informations de décodage à partir de l’événement.

Dans la plupart des cas, les événements sont remis à votre rappel dans l’ordre dans lequel ils se sont produits (ordre d’horodatage). Toutefois, dans certaines circonstances, les événements peuvent ne pas être livrés dans leur commande d’origine.

Si la trace utilise l’heure système pour l’horodatage de session (c’est-à-dire que la session de suivi a été démarrée avec properties.Wnode.ClientContext la valeur 2) et que l’horloge système est ajustée vers l’arrière pendant que la session collecte des événements, certains des événements peuvent être remis dans le désordre. Pour éviter cela, définissez ClientContext sur 0 pour obtenir l’horodatage par défaut (heure QPC).
Si la trace est collectée à l’aide d’horodatages d’une horloge imprécise, les événements avec le même horodatage provenant de différents processeurs peuvent être livrés en désordre. Cela se produit le plus fréquemment lorsque la trace utilise l’heure système pour l’horodatage de session, car l’heure système est cochée. Ce problème peut être évité en commençant la session avec EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING dans les indicateurs LogFileMode , bien que cela puisse avoir un impact négatif considérable sur les performances de suivi. À compter de Windows 10 : le type d’horloge du système utilise GetSystemTimePreciseAsFileTime pour réduire la probabilité de ce problème.
Si la trace est endommagée, a été générée à l’aide d’API de bas niveau qui ne respectent pas les règles d’horodatage attendues dans le fichier ou utilisent des options de remplacement d’horodatage lors de l’écriture d’événements, certains des événements peuvent être remis dans le désordre.

Détails techniques : Les événements sont stockés dans des mémoires tampons. Chaque mémoire tampon est affectée à un flux de mémoire tampon, généralement un flux pour chaque processeur. L’implémentation de ProcessTrace part du principe que tous les événements d’une mémoire tampon sont triés par horodatage et que chaque mémoire tampon contient des événements pendant un laps de temps unique qui ne chevauche pas l’étendue d’une autre mémoire tampon dans le flux de cette mémoire tampon. Lorsque ces hypothèses ne sont pas remplies, ProcessTracepeut fournir des événements dans le désordre.

Lorsqu’une session de collecte de traces en temps réel n’a pas de sessions de traitement de trace associées, les événements collectés sont mis en mémoire tampon par le système jusqu’à ce que la mémoire tampon soit complète. Lorsqu’une session de traitement des traces se connecte à une session de collection de traces en temps réel, la session de traitement de trace reçoit les événements synthétiques de la session, puis les événements mis en mémoire tampon, puis elle commence à recevoir les événements en temps réel nouvellement générés. Si une deuxième session de traitement en temps réel se connecte à la même session de collecte de traces, elle reçoit les événements synthétiques et les événements en temps réel nouvellement générés (la deuxième session de traitement de trace ne recevra pas d’événements plus anciens).

Important

Lors du traitement d’événements à partir d’une session en temps réel, si le rappel de traitement prend trop de temps pour traiter chaque événement et que les événements arrivent trop rapidement, il se retarde. Le système met en mémoire tampon les événements pour éviter la perte de données, mais cela augmente l’utilisation des ressources système (par exemple, l’utilisation de la mémoire et du disque). Évitez ce problème en utilisant des filtres de session (par exemple, des filtres de niveau et de mot clé pour chaque fournisseur) pour réduire le taux d’événements entrants, en effectuant un filtrage anticipé dans votre rappel pour ignorer les événements qui ne nécessitent pas de traitement complet, et en optimisant votre rappel pour qu’il retourne le plus rapidement possible pour éviter de bloquer le thread de traitement.

Pour plus d’informations sur l’interprétation des données d’événement, consultez Consommation d’événements et Récupération de données d’événement à l’aide de TDH.

Spécifications


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	evntrace.h