Fonction ControlTraceA (evntrace.h)

Article
08/23/2023

La fonction ControlTrace vide, interroge, met à jour ou arrête la session de suivi d’événements spécifiée.

Syntaxe

ULONG WMIAPI ControlTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Paramètres

[in] TraceHandle

Gérez vers une session de suivi d’événements, ou 0. Vous devez spécifier un SessionHandle différent de zéro si SessionName a la valeur NULL. ETW ignore le handle si SessionName n’a pas la valeur NULL.

La fonction StartTrace retourne ce handle lorsqu’une nouvelle trace est démarrée. Pour obtenir le handle d’une trace existante, utilisez ControlTrace pour interroger les propriétés de trace en fonction du nom de la trace, puis obtenez le handle à partir du champ Wnode.HistoricalContext des données retournées EVENT_TRACE_PROPERTIES .

[in] InstanceName

Nom d’une session de suivi d’événements, ou NULL. Vous devez spécifier InstanceName si TraceHandle a la valeur 0.

Pour spécifier la session NT Kernel Logger, définissez InstanceNamesur KERNEL_LOGGER_NAME.

[in, out] Properties

Pointeur vers une structure EVENT_TRACE_PROPERTIES initialisée. Cette structure doit être mise à zéro avant de définir des champs.

Si ControlCode spécifie EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY ou EVENT_TRACE_CONTROL_FLUSH, il vous suffit de définir les membres Wnode.BufferSize, Wnode.Guid, LoggerNameOffset et LogFileNameOffset de la structure EVENT_TRACE_PROPERTIES . Si la session est une session privée, vous devez également définir LogFileMode. Vous pouvez utiliser les longueurs maximales de nom de session (1 024 caractères) et de nom de fichier journal (1 024 caractères) pour calculer la taille de la mémoire tampon et les décalages s’ils ne sont pas connus.

Si ControlCode spécifie EVENT_TRACE_CONTROL_UPDATE, lors de l’entrée, les membres doivent spécifier les nouvelles valeurs pour les propriétés à mettre à jour. Dans la sortie, Properties contient les propriétés et les statistiques de la session de suivi d’événements. Vous pouvez mettre à jour les propriétés suivantes.

EnableFlags : définissez ce membre sur 0 pour désactiver tous les fournisseurs système. Définissez cette valeur sur une valeur différente de zéro pour spécifier les fournisseurs système que vous souhaitez activer ou conserver activés. Cela peut être différent de zéro uniquement pour les enregistreurs d’événements système.
FlushTimer : définissez ce membre si vous souhaitez modifier le délai d’attente avant de vider les mémoires tampons. Si ce membre a la valeur 0, le membre n’est pas mis à jour.
LogFileNameOffset : définissez ce membre si vous souhaitez basculer vers un autre fichier journal ou vider une trace en mode de mise en mémoire tampon dans un nouveau fichier journal. Si ce membre est 0, le nom de fichier n’est pas mis à jour. Si le décalage n’est pas égal à zéro et que vous ne modifiez pas le nom du fichier journal, la fonction retourne une erreur.
LogFileMode : définissez ce membre si vous souhaitez activer et désactiver EVENT_TRACE_REAL_TIME_MODE . Pour désactiver le temps réel, définissez ce membre sur 0. Pour activer le temps réel (création d’une session qui enregistre sur le disque et remet des événements en temps réel), définissez ce membre sur EVENT_TRACE_REAL_TIME_MODE et il sera OU’d avec les modes actuels.
MaximumBuffers : définissez ce membre si vous souhaitez modifier le nombre maximal de mémoires tampons qu’ETW utilise. Si ce membre a la valeur 0, le membre n’est pas mis à jour.

Pour les sessions d’enregistreur d’événements privées, vous pouvez mettre à jour uniquement les membres LogFileNameOffset et FlushTimer .

Si vous utilisez une structure EVENT_TRACE_PROPERTIES nouvellement initialisée, supprimez la structure, puis définissez Wnode.BufferSize, Wnode.Guid et Wnode.Flags, ainsi que les valeurs que vous souhaitez mettre à jour.

Si vous réutilisez une structure EVENT_TRACE_PROPERTIES (c’est-à-dire à l’aide d’une structure que vous avez précédemment passée à StartTrace ou ControlTrace), veillez à définir le membre LogFileNameOffset sur 0, sauf si vous modifiez le nom du fichier journal, et veillez à définir EVENT_TRACE_PROPERTIES. Wnode.Flags pour WNODE_FLAG_TRACED_GUID.

À compter de Windows 10, version 1703 : Pour de meilleures performances dans les scénarios interprocesseurs, vous pouvez maintenant transmettre les informations de filtrage à ControlTrace pour les enregistreurs d’événements privés à l’échelle du système. Vous devez utiliser la structure EVENT_TRACE_PROPERTIES_V2 pour inclure les informations de filtrage. Pour plus d’informations, consultez Configuration et démarrage d’une session d’enregistreur d’événements privés .

[in] ControlCode

Fonction de contrôle demandée. Vous pouvez spécifier l'une des valeurs suivantes :

EVENT_TRACE_CONTROL_FLUSH : vide les mémoires tampons actives de la session.

Cela peut être utilisé avec une session en mémoire (une session démarrée avec l’indicateur EVENT_TRACE_BUFFERING_MODE ) pour écrire les données de la trace dans un fichier.

Normalement, vous n’avez pas besoin de vider les sessions basées sur des fichiers ou en temps réel, car ETW vide automatiquement une mémoire tampon lorsqu’elle est pleine (c’est-à-dire lorsqu’elle n’a pas de place pour l’événement suivant), lorsque flushTimer de la session de trace expire ou lorsque la session de trace est fermée.

Windows 2000 : Cette valeur n’est pas prise en charge.
EVENT_TRACE_CONTROL_QUERY : récupère les propriétés et statistiques de session.
EVENT_TRACE_CONTROL_STOP : arrête la session. Le handle de session n’est plus valide.
EVENT_TRACE_CONTROL_UPDATE : Mises à jour les propriétés de session.
EVENT_TRACE_CONTROL_INCREMENT_FILE : si la session a le EVENT_TRACE_FILE_MODE_NEWFILE, met à jour la session pour basculer immédiatement vers le fichier suivant, plutôt que d’attendre que le fichier précédent soit rempli. Pris en charge à partir de Mise à jour d'octobre 2018 de Windows 10.
EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME : remplace une session en mode fichier par une session en temps réel (active la remise en temps réel et désactive l’écriture d’événements dans le fichier ETL). Pris en charge à partir de Windows 10 mise à jour d’octobre 2020.

Notes

Il n’est pas sûr de vider les mémoires tampons ou d’arrêter une session de trace à partir de DllMain (peut entraîner un blocage).

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système. Voici quelques erreurs courantes et leurs causes.

ERROR_BAD_LENGTH

Une des conditions suivantes est vraie :
- Le membre Wnode.BufferSize de Properties spécifie une taille incorrecte.
- Les propriétés ne disposent pas d’un espace suffisant pour contenir une copie du nom de session et du nom du fichier journal (le cas échéant).
ERROR_INVALID_PARAMETER

Une des conditions suivantes est vraie :
- Les propriétés ont la valeur NULL.
- InstanceName et TraceHandle sont tous deux NULL.
- InstanceName a la valeur NULL et TraceHandle n’est pas un handle valide.
- Le membre LogFileNameOffset de Properties n’est pas valide.
- Le membre LoggerNameOffset de Properties n’est pas valide.
- Le membre LogFileMode de Properties spécifie une combinaison d’indicateurs qui n’est pas valide.
- Le membre Wnode.Guid de Properties est SystemTraceControlGuid, mais le paramètre InstanceName n’est pas KERNEL_LOGGER_NAME.
ERROR_BAD_PATHNAME

Une autre session utilise déjà le nom de fichier spécifié par le membre LogFileNameOffset de la structure Properties .
ERROR_MORE_DATA

La mémoire tampon pour EVENT_TRACE_PROPERTIES est trop petite pour contenir toutes les informations de la session. Si vous n’avez pas besoin des informations de propriété de la session, vous pouvez ignorer cette erreur. Si vous recevez cette erreur lors de l’arrêt de la session, ETW a déjà arrêté la session avant de générer cette erreur.
ERROR_ACCESS_DENIED

Seuls les utilisateurs exécutant des privilèges d’administration élevés, les utilisateurs du groupe Utilisateurs du journal des performances et les services exécutés en tant que LocalSystem, LocalService, NetworkService peuvent contrôler les sessions de suivi des événements. Pour accorder à un utilisateur restreint la possibilité de contrôler les sessions de suivi, ajoutez-les au groupe Utilisateurs du journal de performances. Seuls les utilisateurs disposant de privilèges d’administration et de services s’exécutant en tant que LocalSystem peuvent contrôler une session d’enregistreur d’événements du noyau NT.

Windows XP et Windows 2000 : Tout le monde peut contrôler une session de suivi.
ERROR_WMI_INSTANCE_NOT_FOUND

La session donnée n’est pas en cours d’exécution.

Remarques

Les contrôleurs de trace d’événements appellent cette fonction.

Cette fonction remplace les fonctions FlushTrace, QueryTrace, StopTrace et UpdateTrace .

Notes

L’en-tête evntrace.h définit ControlTrace en tant qu’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. La combinaison 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 \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	evntrace.h
Bibliothèque	Sechost.lib sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.lib sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP
DLL	Sechost.dll sur Windows 8.1 et Windows Server 2012 ; Advapi32.dll sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP

Voir aussi

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace