structure EVENT_TRACE_PROPERTIES (evntrace.h)

La structure EVENT_TRACE_PROPERTIES contient des informations sur une session de suivi d’événements. Vous utilisez cette structure avec des API telles que StartTrace et ControlTrace lors de la définition, de la mise à jour ou de l’interrogation des propriétés d’une session.

Syntaxe

typedef struct _EVENT_TRACE_PROPERTIES {
  WNODE_HEADER Wnode;
  ULONG        BufferSize;
  ULONG        MinimumBuffers;
  ULONG        MaximumBuffers;
  ULONG        MaximumFileSize;
  ULONG        LogFileMode;
  ULONG        FlushTimer;
  ULONG        EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG        NumberOfBuffers;
  ULONG        FreeBuffers;
  ULONG        EventsLost;
  ULONG        BuffersWritten;
  ULONG        LogBuffersLost;
  ULONG        RealTimeBuffersLost;
  HANDLE       LoggerThreadId;
  ULONG        LogFileNameOffset;
  ULONG        LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Membres

Wnode

Structure WNODE_HEADER . Vous devez spécifier les membres BufferSize, Flags et Guid . Vous pouvez éventuellement spécifier le membre ClientContext .

BufferSize

Kilo-octets de mémoire alloués pour chaque mémoire tampon de session de suivi d’événements. La taille minimale de la mémoire tampon est de 4 (4 Ko). La taille maximale de la mémoire tampon est 16384 (16 Mo). La plupart des sessions de suivi doivent utiliser une taille de mémoire tampon de 64 Ko ou moins pour éviter de gaspiller la mémoire et l’espace disque. Avant Windows 8 : la taille maximale de la mémoire tampon est de 1024 (1 Mo).

Des tailles de mémoire tampon plus petites réduisent l’utilisation de la mémoire de session et peuvent aider à réduire la taille du fichier journal. Les tailles de mémoire tampon plus grandes prennent en charge la collecte d’événements plus importants, car ETW ne fragmente pas les événements entre les limites de la mémoire tampon et ne peut donc pas collecter les événements supérieurs à la taille de la mémoire tampon. Dans les scénarios impliquant un débit de données extrêmement élevé, des tailles de mémoire tampon plus importantes peuvent également réduire la surcharge du processeur.

• Une session avec de petits événements et un faible taux d’événements (quelques Ko/s) doit utiliser une petite taille de mémoire tampon (4 Ko à 16 Ko).
• Une session avec de petits événements et un taux d’événements modéré doit utiliser une taille de mémoire tampon moyenne (16 Ko à 32 Ko).
• Une session avec des événements volumineux ou un taux d’événements élevé (quelques Mo/s) doit utiliser une grande taille de mémoire tampon (64 Ko à 128 Ko).
• Dans de rares cas où une grande quantité de mémoire doit être réservée à une trace de diagnostic avec des centaines de mégaoctets de données par seconde, une énorme taille de mémoire tampon (256 Ko à 1 024 Ko) peut réduire la surcharge du processeur.

ETW peut ajuster la taille de mémoire tampon demandée vers le haut dans certains scénarios. Par exemple, lors de l’écriture d’un fichier de trace sur un disque, ETW peut augmenter la taille de la mémoire tampon à un multiple de la taille du bloc physique du disque.

MinimumBuffers

Nombre minimal de mémoires tampons réservées pour le pool de mémoires tampons de la session de suivi.

ETW peut ajuster cette valeur dans certains scénarios.

• Si le mode de journalisation inclut l’indicateur EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING , ETW réserve au moins 2 mémoires tampons.
• Si le mode de journalisation n’inclut pas l’indicateur EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING , ETW réserve au moins 2 mémoires tampons pour chaque processeur logique.
• Si cette valeur est supérieure à une limite déterminée par ETW, ETW peut la réduire à la limite pour éviter une utilisation excessive de la mémoire.

Pour les suivis en mode fichier et en temps réel avec des taux d’événements modérés, la plupart des utilisateurs doivent réduire l’utilisation de la mémoire en définissant MinimumBuffers sur 0 ou sur un petit minimum (par exemple, 4 ou 8), ce qui permet à ETW d’ajuster la valeur vers le haut en fonction du nombre de processeurs. ETW réserve le nombre minimal de mémoires tampons (ajusté) au démarrage de la trace. Si les mémoires tampons sont remplies plus rapidement qu’elles ne peuvent être traitées, ETW essaie d’allouer des mémoires tampons supplémentaires, jusqu’au nombre spécifié par MaximumBuffers.

Pour les suivis en mode mémoire tampon (circulaire en mémoire), les utilisateurs doivent définir le paramètre MinimumBuffers en fonction de la quantité totale de mémoire que vous souhaitez réserver à ETW pour la session. Cette valeur est généralement calculée en fonction du taux d’événements attendu et de la durée pendant laquelle vous souhaitez que la trace couvre. Par exemple, si vous prévoyez un débit de données de 16 Ko par seconde et que vous souhaitez que votre trace enregistre au moins 60 secondes de données, vous avez besoin de 960 Ko. En supposant une taille de mémoire tampon de 32 Ko, vous définissez MinimumBuffers sur 30 (960 Ko au total / 32 Ko par mémoire tampon = 30 mémoires tampons). ETW réserve le nombre minimal de mémoires tampons (ajusté) au démarrage de la trace. Lorsque toutes les mémoires tampons sont remplies, ETW réutilise la mémoire tampon remplie la plus ancienne pour les nouveaux événements. Notez qu’ETW n’allouera pas de mémoires tampons supplémentaires (ETW ignore MaximumBuffers pour les traces en mode de mise en mémoire tampon).

MaximumBuffers

Nombre maximal de mémoires tampons à allouer pour le pool de mémoires tampons de la session de suivi.

ETW peut ajuster cette valeur dans certains scénarios.

• Si cette valeur est inférieure à la valeur ajustée de MinimumBuffers, ETW peut l’augmenter à une valeur appropriée égale ou supérieure à MinimumBuffers.
• Si cette valeur est supérieure à une limite déterminée par ETW, ETW peut la réduire à la limite.

La plupart des utilisateurs doivent commencer à paramétrer leur session en définissant MinimumBuffers et MaximumBuffers sur la même valeur. Vous pouvez alors augmenter la valeur de MaximumBuffers si la trace supprime les événements pendant les pics de fréquence d’événements.

ETW ne peut pas allouer de mémoires tampons à la demande si l’événement est généré par un pilote s’exécutant à un taux d’IRQL élevé. Si votre session de suivi doit enregistrer des événements à partir de fournisseurs en mode noyau à haut niveau d’IRQL, il peut être nécessaire d’utiliser une valeur supérieure de MinimumBuffers pour forcer la préallouer les mémoires tampons.

MaximumFileSize

Taille maximale du fichier utilisé pour journaliser les événements, en mégaoctets, ou zéro pour aucune limite de taille. En règle générale, vous utilisez ce membre pour limiter la taille d’un fichier journal circulaire lorsque vous définissez LogFileMode sur EVENT_TRACE_FILE_MODE_CIRCULAR. Ce membre doit être défini sur une valeur différente de zéro si LogFileMode contient EVENT_TRACE_FILE_MODE_PREALLOCATEou EVENT_TRACE_FILE_MODE_CIRCULAREVENT_TRACE_FILE_MODE_NEWFILE.

Si vous utilisez le lecteur système (le lecteur qui contient le système d’exploitation) pour la journalisation, ETW recherche 200 Mo d’espace disque supplémentaire, que vous utilisiez ou non le paramètre de taille de fichier maximale. Par conséquent, si vous spécifiez 100 Mo comme taille de fichier maximale pour le fichier de trace dans le lecteur système, vous devez disposer de 300 Mo d’espace libre sur le lecteur.

LogFileMode

Indicateurs de journalisation pour la session de suivi d’événements. Vous utilisez ce membre pour spécifier si vous souhaitez écrire des événements dans une mémoire tampon circulaire en mémoire, un fichier journal ou un consommateur en temps réel. Vous pouvez également utiliser ce membre pour spécifier d’autres caractéristiques de session, par exemple, que la session est une session d’enregistreur d’événements privé. Pour obtenir la liste des indicateurs possibles, consultez Constantes du mode de journalisation.

ETW met en mémoire tampon les événements pour les sessions en temps réel lorsqu’il n’y a pas de consommateurs en temps réel pour la session. Notez que cette mise en mémoire tampon est limitée. Si la limite est atteinte, les nouveaux événements sont ignorés et les fonctions de journalisation échouent avec STATUS_LOG_FILE_FULL. Avant Windows Vista : S’il n’existe aucun consommateur en temps réel, les événements sont ignorés et la journalisation continue.

Ne démarrez pas une session de journalisation en temps réel, sauf si un consommateur en temps réel consomme les événements. Une session en temps réel sans consommateurs gaspillera les ressources système (processeur, mémoire et espace disque pour la mise en mémoire tampon des événements).

Si un consommateur commence à traiter les événements en temps réel, les événements mis en mémoire tampon sont consommés en premier. Une fois que tous les événements mis en mémoire tampon sont consommés, la session commence à signaler de nouveaux événements.

FlushTimer

À quelle fréquence, en secondes, toutes les mémoires tampons de trace non vides sont vidées. La durée minimale de vidage est de 1 seconde.

• Pour les sessions en mode fichier : la définition de FlushTimer sur 0 désactive les vidages basés sur le temps (le vidage se produit lorsque la mémoire tampon est remplie, lorsque la session est arrêtée ou lorsque la session est explicitement vidée). La plupart des traces en mode fichier doivent définir FlushTimer sur 0 pour éviter le gaspillage d’espace dans le fichier de suivi (c’est-à-dire afin que l’espace disque ne soit pas gaspiller en stockant principalement des mémoires tampons vides). Vous pouvez définir le minuteur sur une valeur autre que zéro s’il est possible que la trace ne soit pas fermée (par exemple, si vous souhaitez être sûr d’obtenir des événements même si le système se bloque).
• Pour les sessions en temps réel : la définition de FlushTimer sur 0 active un délai d’expiration par défaut de 1 seconde. Les sessions en temps réel doivent définir le minuteur de vidage en fonction de la rapidité à laquelle les données doivent être reçues. Notez qu’une valeur de minuterie plus élevée réduit la surcharge processeur pour la trace. La plupart des traces en temps réel doivent commencer par un minuteur de 5 ou 10 secondes et régler le minuteur en fonction des besoins.
• Pour les sessions en mémoire tampon (circulaires en mémoire), FlushTimer n’est pas utilisé. Les données de trace ne seront vidées qu’à la demande (par exemple, vidées dans un fichier via ControlTrace).

EnableFlags

Une session d’enregistreur d’événements système peut définir EnableFlags pour indiquer quels événements SystemTraceProvider doivent être inclus dans la trace.

Ce membre peut contenir une ou plusieurs des valeurs suivantes. En plus des événements que vous spécifiez, sauf si vous spécifiez EVENT_TRACE_FLAG_NO_SYSCONFIG, l’enregistreur d’événements enregistre également les événements de configuration matérielle sur Windows XP et les événements de configuration système sur Windows Server 2003 ou version ultérieure.

• EVENT_TRACE_FLAG_ALPC (0x00100000)

  Active les types d’événements ALPC .

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_CSWITCH (0x00000010)

  Active le type d’événement Thread suivant :

  • CSwitch

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_DBGPRINT (0x00040000)

  Permet de convertir les appels DbgPrint et DbgPrintEx en événements ETW.

• EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)

  Active le type d’événement FileIo suivant (vous devez également activer EVENT_TRACE_FLAG_DISK_IO) :

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  Active les types d’événements DiskIo suivants :

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  Active le type d’événement DiskIo suivant :

  • DiskIo_TypeGroup2

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  Active le type d’événement Thread suivant :

  • ReadyThread

  Cette valeur est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.

• EVENT_TRACE_FLAG_DPC (0x00000020)

  Active le type d’événement PerfInfo suivant :

  • différé, appel de processus

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  Active les types d’événements DiskIo suivants :

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  Active les types d’événements FileIo suivants :

  • FileIo_OpEnd

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  Active le type d’événement FileIo suivant :

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  Active le type d’événement Image suivant :

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  Active le type d’événement PerfInfo suivant :

  • ISR

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_JOB (0x00080000)

  Cette valeur est prise en charge sur Windows 10

• EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)

  Active le type d’événement PageFault_V2 suivant :

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  Active le type d’événement PageFault_V2 suivant :

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)

  Active les types d’événements TcpIp et UdpIp .

• EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)

  N’effectuez pas d’exécution de configuration système.

  Cette valeur est prise en charge sur Windows 8, Windows Server 2012 et versions ultérieures.

• EVENT_TRACE_FLAG_PROCESS (0x00000001)

  Active le type d’événement Process suivant :

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  Active le type d’événement Process_V2 suivant :

  • Process_V2_TypeGroup2

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  Active le type d’événement PerfInfo suivant :

  • SampledProfile

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_REGISTRY (0x00020000)

  Active les types d’événements registry .

• EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)

  Active les types d’événements SplitIo .

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)

  Active le type d’événement PerfInfo suivant :

  • SysCallEnter
  • SysCallExit

  Cette valeur est prise en charge sur Windows Vista et versions ultérieures.

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  Active le type d’événement Thread suivant :

  • Thread_TypeGroup1

• EVENT_TRACE_FLAG_VAMAP (0x00008000)

  Active le type d’événement map and unmap (à l’exception des fichiers image).

  Cette valeur est prise en charge sur Windows 8, Windows Server 2012 et versions ultérieures.

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)

  Active le type d’événement PageFault_V2 suivant :

  • PageFault_VirtualAlloc

  Cette valeur est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.

DUMMYUNIONNAME

DUMMYUNIONNAME.AgeLimit

Non utilisé.

Windows 2000 : Délai avant que les mémoires tampons inutilisées ne soient libérées, en minutes. La valeur par défaut est 15 minutes.

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

En sortie, nombre de mémoires tampons allouées pour le pool de mémoires tampons de la session de suivi d’événements.

FreeBuffers

En sortie, nombre de mémoires tampons allouées mais inutilisées dans le pool de mémoires tampons de la session de suivi d’événements.

EventsLost

Lors de la sortie, nombre d’événements qui n’ont pas été enregistrés.

BuffersWritten

En sortie, nombre de mémoires tampons écrites.

LogBuffersLost

En sortie, nombre de mémoires tampons qui n’ont pas pu être écrites dans le fichier journal.

RealTimeBuffersLost

En sortie, nombre de mémoires tampons qui n’ont pas pu être remises en temps réel au consommateur.

LoggerThreadId

Lors de la sortie, identificateur de thread pour la session de suivi d’événements.

LogFileNameOffset

Décalage (en octets) du début de la mémoire allouée de cette structure au début de la chaîne terminée par un nul qui contient le nom du fichier journal.

Le nom de fichier a normalement une .etl extension. Tous les dossiers du chemin d’accès doivent déjà exister (ETW ne crée pas de dossiers pour vous). Le chemin peut être relatif, absolu, local ou distant. Les variables d’environnement dans le chemin d’accès ne seront pas développées. L’utilisateur doit être autorisé à écrire dans le dossier .

Le nom du fichier journal est limité à 1 024 caractères. Si vous définissez LogFileMode sur EVENT_TRACE_PRIVATE_LOGGER_MODE ou EVENT_TRACE_FILE_MODE_NEWFILE, veillez à réserver suffisamment de mémoire pour inclure l’identificateur de processus qui sera ajouté au nom de fichier pour les sessions d’enregistreurs d’événements privés et le numéro séquentiel ajouté aux fichiers journaux créés à l’aide du nouveau mode journal des fichiers.

Si vous ne souhaitez pas journaliser les événements dans un fichier journal (par exemple, si vous spécifiez EVENT_TRACE_REAL_TIME_MODE uniquement), définissez LogFileNameOffset sur 0. Si vous spécifiez uniquement la journalisation en temps réel et que vous fournissez également un décalage avec un nom de fichier journal valide, ETW utilise le nom du fichier journal pour créer un fichier journal séquentiel et des événements de journalisation dans le fichier journal en plus d’envoyer les événements aux consommateurs en temps réel. ETW crée également le fichier journal séquentiel si LogFileMode a la valeur 0 et que vous fournissez un décalage avec un nom de fichier journal valide.

Si vous souhaitez enregistrer des événements dans un fichier journal, vous devez réserver suffisamment de mémoire pour que cette structure inclue le nom du fichier journal et le nom de session qui suivent la structure. Le nom du fichier journal doit suivre le nom de session en mémoire. Consultez les remarques pour obtenir un exemple.

Les fichiers de trace sont créés à l’aide du descripteur de sécurité par défaut, ce qui signifie que le fichier journal aura la même liste de contrôle d’accès que le répertoire parent. Si vous souhaitez que l’accès aux fichiers soit restreint, créez un répertoire parent avec les listes de contrôle d’accès appropriées.

LoggerNameOffset

Décalage (en octets) du début de la mémoire allouée de la structure au début de la chaîne terminée par un nul qui contient le nom de session.

Le nom de session est limité à 1 024 caractères. Le nom de session ne respecte pas la casse. Le système ne démarre pas une nouvelle session si une autre session portant le même nom est déjà en cours d’exécution.

Windows 2000 : Les noms de session respectent la casse. Par conséquent, les sessions dont les noms diffèrent uniquement en cas de cas sont autorisées. Toutefois, pour réduire la confusion, vous devez vous assurer que les noms de vos sessions sont uniques.

Remarques

Lorsque vous allouez la mémoire pour cette structure, vous devez allouer suffisamment de mémoire pour inclure le nom de session et le nom du fichier journal qui suit la structure. Le nom de session doit être antérieur au nom du fichier journal en mémoire. Vous devez copier le nom du fichier journal sur le décalage, mais vous ne copiez pas le nom de session dans le décalage. La fonction StartTrace copie le nom pour vous.

Veillez à initialiser la mémoire de cette structure sur zéro avant de définir des membres. Par exemple :

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

Les événements des fournisseurs sont écrits dans les mémoires tampons d’une session. Lorsqu’une mémoire tampon dans un fichier ou une session en temps réel est saturée (ou lorsque FlushTimer expire), la session vide la mémoire tampon en écrivant les événements dans un fichier journal, en les remettant à un consommateur en temps réel, ou les deux. Si les mémoires tampons d’une session sont remplies plus rapidement qu’elles ne peuvent être vidées, de nouvelles mémoires tampons sont allouées et ajoutées au pool de mémoires tampons de la session, jusqu’à MaximumBuffers. Au-delà de cette limite, la session ignore les événements entrants jusqu’à ce qu’une mémoire tampon soit disponible. Chaque session conserve un enregistrement du nombre d’événements ignorés (voir le membre EventsLost ).

Pour afficher les statistiques de session, telles que EventsLost pendant l’exécution de la session, appelez la fonction ControlTrace et définissez le paramètre ControlCode sur EVENT_TRACE_CONTROL_QUERY.

Configuration requise

Voir aussi

StartTrace

ControlTrace

QueryAllTraces

Constantes du mode journalisation

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER