Partager via

structure EVENT_TRACE_LOGFILEW (evntrace.h)

  • Article

La structure EVENT_TRACE_LOGFILE stocke des informations sur une source de données de trace.

La structure EVENT_TRACE_LOGFILE est utilisée lors de l’appel d’OpenTrace. L’utilisateur fournit une structure EVENT_TRACE_LOGFILE avec des informations sur la source de données de trace (soit le nom d’un fichier ETL, soit le nom d’une session d’enregistreur d’événements en temps réel active), les indicateurs de traitement des traces et les fonctions de rappel qui recevront des données de trace. En cas de réussite, OpenTrace remplit les champs restants de la structure pour retourner des détails sur la source de données de trace.

Lorsque ProcessTrace traite une mémoire tampon, il appelle le BufferCallback défini par l’utilisateur avec une structure EVENT_TRACE_LOGFILE pour fournir des informations sur la session de traitement des événements et la mémoire tampon.

Syntaxe

typedef struct _EVENT_TRACE_LOGFILEW {
  LPWSTR                        LogFileName;
  LPWSTR                        LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;

Membres

LogFileName

Nom du fichier journal en cours de traitement ou NULL si les données d’une session de suivi en temps réel sont traitées. Spécifiez une valeur pour ce membre si vous appelez OpenTrace pour consommer des données à partir d’un fichier journal.

Lors de l’appel d’OpenTrace, si LoggerName n’a pas la valeur NULL , LogFileName doit avoir la valeur NULL.

Lors de l’appel d’OpenTrace, l’utilisateur qui consomme les événements doit disposer des autorisations nécessaires pour lire le fichier.

Notes

Le nom de fichier fourni à OpenTrace via le champ LogFileName doit être le nom de fichier complet, y compris les suffixes. Certaines API de création de fichiers de trace peuvent ajouter en mode silencieux un suffixe au nom de fichier spécifié par l’utilisateur. Par exemple, si le contrôleur a enregistré des événements dans une session privée (le contrôleur définit le membre LogFileMode de EVENT_TRACE_PROPERTIES sur EVENT_TRACE_PRIVATE_LOGGER_MODE lors de l’appel de StartTrace), le fichier ETL généré inclut un suffixe d’ID de processus, par exemple mytrace.etl_123. Cela peut également se produire si le fichier a été créé à l’aide du mode EVENT_TRACE_FILE_MODE_NEWFILE , auquel cas le fichier ETL généré inclut un numéro de séquence.

LoggerName

Nom de la session de suivi des événements en temps réel ou NULL si les données d’un fichier journal sont traitées. Spécifiez une valeur pour ce membre si vous appelez OpenTrace pour consommer des données d’une session en temps réel.

Lors de l’appel d’OpenTrace, si LogFileName n’a pas la valeur NULL , LoggerName doit avoir la valeur NULL.

Vous ne pouvez consommer des événements en temps réel que si le contrôleur de trace a défini le membre LogFileMode de EVENT_TRACE_PROPERTIES pour inclure l’indicateur EVENT_TRACE_REAL_TIME_MODE .

Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du groupe Utilisateurs du journal des performances et les applications s’exécutant en tant que LocalSystem, LocalService, NetworkService peuvent consommer des événements en temps réel. Pour accorder à un utilisateur restreint la possibilité de consommer des événements en temps réel, ajoutez-les au groupe Utilisateurs du journal des performances ou appelez EventAccessControl.

Windows XP et Windows 2000 : Tout le monde peut consommer des événements en temps réel.

CurrentTime

Sur la sortie, l’heure actuelle, par intervalles de 100 nanosecondes depuis minuit, le 1er janvier 1601.

BuffersRead

En sortie, le nombre de mémoires tampons traitées.

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

Réservé. Ne pas utiliser.

DUMMYUNIONNAME.ProcessTraceMode

Modes pour le traitement des événements. Les modes sont définis dans le fichier d’en-tête evntcons.h . Vous pouvez spécifier un ou plusieurs des modes suivants :

  • PROCESS_TRACE_MODE_EVENT_RECORD

    Spécifiez ce mode si vous souhaitez recevoir des événements dans le nouveau format EVENT_RECORD (fortement recommandé). Pour recevoir des événements dans le nouveau format, vous devez spécifier un rappel dans le membre EventRecordCallback . Si vous ne spécifiez pas ce mode, vous recevrez des événements dans l’ancien format via le rappel spécifié dans le membre EventCallback .

    Avant Windows Vista : Non pris en charge.

  • PROCESS_TRACE_MODE_RAW_TIMESTAMP

    Par défaut, ProcessTrace convertit le TimeStamp de l’événement au format brut d’origine (heure système, heure QPC ou compteur de cycle du processeur) en heure système (intervalles de 100 nanosecondes depuis minuit, le 1er janvier 1601).

    Spécifiez l’indicateur PROCESS_TRACE_MODE_RAW_TIMESTAMP si vous ne souhaitez pas que la valeur d’horodatage dans le membre TimeStamp de EVENT_HEADER et EVENT_TRACE_HEADER convertie en heure système. Si cet indicateur est spécifié, ProcessTrace laisse la valeur d’horodatage au format d’origine spécifié par le contrôleur dans le membre Wnode.ClientContext de EVENT_TRACE_PROPERTIES.

    Avant Windows Vista : Non pris en charge.

  • PROCESS_TRACE_MODE_REAL_TIME

    Spécifiez ce mode pour recevoir des événements en temps réel. Vous devez spécifier ce mode si LoggerName n’a pas la valeur NULL.

CurrentEvent

Lors de la sortie, une structure EVENT_TRACE qui contient le dernier événement traité.

LogfileHeader

En sortie, une structure de TRACE_LOGFILE_HEADER qui contient des informations générales sur la session et l’ordinateur sur lequel la session s’est exécutée.

BufferCallback

Pointeur vers la fonction BufferCallback qui reçoit des statistiques liées à la mémoire tampon pour chaque vidage ETW de mémoire tampon. ETW appelle ce rappel après avoir émis tous les événements dans la mémoire tampon. Ce rappel est facultatif.

BufferSize

Sur la sortie, contient la taille de chaque mémoire tampon, en octets.

Filled

Sur la sortie, contient le nombre d’octets dans la mémoire tampon qui contiennent des informations valides.

EventsLost

Non utilisé.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

Pointeur vers la fonction EventCallback que ETW appelle pour chaque événement de la mémoire tampon. Ce champ est utilisé uniquement si le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .

Notes

Le champ EventCallback sera traité comme un EventRecordCallback si le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD . Si votre EventCallback reçoit des données garblées de ProcessTrace, vérifiez que le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .

Conseil

Le nouveau code doit utiliser EventRecordCallback au lieu d’EventCallback. EventRecordCallback reçoit un EVENT_RECORD qui contient des informations d’événement plus complètes, peut être utilisé avec des API de décodage telles que TdhGetEventInformation, et a un pointeur de contexte qui peut être utilisé par votre rappel.

DUMMYUNIONNAME2.EventRecordCallback

Pointeur vers la fonction EventRecordCallback que ETW appelle pour chaque événement de la mémoire tampon. Ce champ est utilisé uniquement si le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .

Notes

Le champ EventRecordCallback sera traité comme un EventCallback si le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD . Si votre EventRecordCallback reçoit des données altérées de ProcessTrace, vérifiez que le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .

Avant Windows Vista : Non pris en charge.

IsKernelTrace

Sur la sortie, si ce membre a la valeur TRUE, la session de suivi des événements est l’enregistreur d’événements NT Kernel Logger. Sinon, il s’agit d’une autre session de suivi d’événements.

Context

Données de contexte qu’un consommateur peut spécifier lors de l’appel d’OpenTrace. Si le consommateur utilise EventRecordCallback pour consommer des événements, ETW définit le membre UserContext de la structure EVENT_RECORD sur cette valeur.

Avant Windows Vista : Non pris en charge.

Remarques

Les consommateurs d’événements doivent :

  1. Initialisez la mémoire de cette structure à zéro.
  2. Si vous lisez à partir d’un fichier ETL, définissez LogFileName sur le chemin d’accès au fichier. Sinon (par exemple, en cas de lecture à partir d’une session en temps réel), définissez LoggerName sur le nom de la session et définissez ProcessTraceMode sur PROCESS_TRACE_MODE_REAL_TIME.
  3. Si vous utilisez EventRecordCallback (recommandé), définissez EventRecordCallback sur l’adresse de votre fonction de rappel d’enregistrement d’événement, définissez Context sur une valeur à fournir à votre rappel et ajoutez PROCESS_TRACE_MODE_EVENT_RECORDà ProcessTraceMode. Sinon (par exemple, si vous utilisez EventCallback), définissez EventCallback sur l’adresse de votre fonction de rappel d’événement.
  4. Si vous avez besoin d’un rappel après le traitement de chaque mémoire tampon, définissez BufferCallback sur l’adresse de votre fonction de rappel de mémoire tampon.
  5. Si vous souhaitez obtenir les données d’horodatage brutes d’origine au lieu de l’horodatage traité, ajoutez PROCESS_TRACE_MODE_RAW_TIMESTAMP à ProcessTraceMode.
  6. Appelez OpenTrace. Notez que si elle réussit, la fonction OpenTrace remplit les membres de cette structure avec des informations provenant de la source de données de trace.
  7. Appelez ProcessTrace avec le handle retourné par OpenTrace.
    • ProcessTrace appelle votre fonction de rappel d’événement pour chaque événement.
    • ProcessTrace appellera votre fonction de rappel de mémoire tampon (si elle est fournie) après avoir terminé chaque mémoire tampon et inclura une instance de la structure de EVENT_TRACE_LOGFILE avec le traitement des traces status informations.
  8. Une fois le traitement de la trace terminé, appelez CloseTrace pour fermer le handle retourné par OpenTrace.

Notes

L’en-tête evntrace.h définit EVENT_TRACE_LOGFILE comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
En-tête evntrace.h

Voir aussi

BufferCallback

EventRecordCallback

OpenTrace