Fonction EnableTrace (evntrace.h)

Article
06/12/2024

Un contrôleur de session de suivi appelle EnableTrace pour configurer la façon dont un fournisseur d’événements ETW consigne les événements dans une session de suivi.

Cette fonction est obsolète. La fonction EnableTraceEx2 remplace cette fonction.

Syntaxe

ULONG WMIAPI EnableTrace(
  [in] ULONG           Enable,
  [in] ULONG           EnableFlag,
  [in] ULONG           EnableLevel,
  [in] LPCGUID         ControlGuid,
       CONTROLTRACE_ID TraceId
);

Paramètres

[in] Enable

Définissez la valeur 1 pour activer la réception des événements du fournisseur ou pour ajuster les paramètres utilisés lors de la réception des événements du fournisseur (par exemple, pour modifier le niveau et les mots clés). Définissez sur 0 pour désactiver la réception des événements du fournisseur.

[in] EnableFlag

Masque de bits 32 bits de mots clés qui déterminent les catégories d’événements que vous souhaitez que le fournisseur écrive. Le fournisseur écrit généralement un événement si les bits de mot clé de l’événement correspondent à l’un des bits définis dans cette valeur ou si l’événement n’a pas de bits de mot clé défini, en plus de répondre au critera EnableLevel .

Notes

Les fournisseurs basés sur EventRegister prennent en charge les mots clés 64 bits. Utilisez EnableTraceEx2 pour activer les fournisseurs à l’aide d’un masque MatchAnyKeyword 64 bits.

[in] EnableLevel

Valeur qui indique le niveau maximal d’événements que vous souhaitez que le fournisseur écrive. Le fournisseur écrit généralement un événement si le niveau de l’événement est inférieur ou égal à cette valeur, en plus de répondre aux critères EnableFlag .

Cette valeur doit être comprise entre 1 et 255. Microsoft définit la sémantique des niveaux 1 à 5, comme indiqué ci-dessous. Les valeurs inférieures indiquent des événements plus graves. Chaque valeur d’EnableLevel active le niveau spécifié et tous les niveaux plus sévères. Par exemple, si vous spécifiez TRACE_LEVEL_WARNING, votre consommateur recevra des événements d’avertissement, d’erreur et critiques.

Valeur	Signification
TRACE_LEVEL_CRITICAL (1)	Événements de sortie ou d’arrêt anormaux
TRACE_LEVEL_ERROR (2)	Événements d’erreur grave
TRACE_LEVEL_WARNING (3)	Événements d’avertissement tels que les échecs d’allocation
TRACE_LEVEL_INFORMATION (4)	Événements d’information sans erreur
TRACE_LEVEL_VERBOSE (5)	Événements de diagnostic détaillés

Les TRACE_LEVEL constantes sont définies dans evntrace.h. Les constantes équivalentes WINMETA_LEVEL sont définies dans winmeta.h.

[in] ControlGuid

GUID de contrôle (ID de fournisseur) du fournisseur d’événements que vous souhaitez activer ou désactiver.

TraceId

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_INVALID_PARAMETER

Une des conditions suivantes est vraie :
- ControlGuid a la valeur NULL.
- TraceHandle a la valeur NULL.
ERROR_INVALID_FUNCTION

Vous ne pouvez pas modifier les indicateurs d’activation et le niveau lorsque le fournisseur n’est pas inscrit.
ERROR_WMI_GUID_NOT_FOUND

Le fournisseur n’est pas inscrit. Se produit lorsque KB307331 ou Windows 2000 Service Pack 4 est installé et que le fournisseur n’est pas inscrit. Pour éviter cette erreur, le fournisseur doit d’abord être inscrit.
ERROR_NO_SYSTEM_RESOURCES

Dépassement du nombre de sessions de suivi pouvant activer le fournisseur.
ERROR_ACCESS_DENIED

Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du Performance Log Users groupe et les services exécutant LocalSystem, LocalServiceou NetworkService peuvent activer les fournisseurs d’événements dans une session inter-processus. Pour accorder à un utilisateur restreint la possibilité d’activer un fournisseur d’événements, ajoutez-le au Performance Log Users groupe ou consultez EventAccessControl.

Windows XP et Windows 2000 : Tout le monde peut activer un fournisseur d’événements.

Remarques

Les contrôleurs de suivi d’événements appellent cette fonction pour configurer les fournisseurs d’événements qui écrivent des événements dans la session. Par exemple, un contrôleur peut appeler cette fonction pour commencer à collecter des événements à partir d’un fournisseur, pour ajuster le niveau ou les mots clés des événements collectés auprès d’un fournisseur, ou pour arrêter la collecte d’événements à partir d’un fournisseur.

Cette fonction est obsolète. Pour des fonctionnalités supplémentaires, le nouveau code doit utiliser EnableTraceEx2.

Les deux appels de fonction suivants sont équivalents :

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Pour plus d’informations sur la sémantique de la configuration des fournisseurs pour une session, reportez-vous à la documentation d’EnableTraceEx2.

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	Advapi32.lib
DLL	Advapi32.dll

Voir aussi

StartTrace

EnableTraceEx2

Partager via