Partager via

Fonction EnableTraceEx (evntrace.h)

  • Article

Un contrôleur de session de suivi appelle EnableTraceEx 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 EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Paramètres

[in] ProviderId

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

[in, optional] SourceId

GUID qui peut identifier de manière unique la source de cette demande de configuration, ou NULL si aucune identité source n’est nécessaire (équivalent à la définition de SourceId sur &GUID_NULL). Si elle est spécifiée, cette valeur est utilisée comme paramètre SourceId lors de l’appel de l’option EnableCallback du fournisseur.

Notes

Il n’existe pas toujours de mappage direct entre un appel à EnableTrace et un appel correspondant à EnableCallback du fournisseur. Par exemple, si EnableTrace est appelé pour un fournisseur qui n’a pas encore été inscrit, l’appel à EnableCallback est différé jusqu’à ce que l’inscription se produise, et si une session consommateur de trace est arrêtée, ETW appelle EnableCallback même s’il n’y a pas eu d’appel correspondant à EnableTrace. Dans ce cas, EnableTrace est appelé avec SourceId défini sur GUID_NULL.

TraceId

[in] IsEnabled

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] Level

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 MatchAnyKeyword et MatchAllKeyword .

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] MatchAnyKeyword

Masque de bits 64 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 aux critères Level et MatchAllKeyword .

[in] MatchAllKeyword

Masque de bits 64 bits de mots clés qui limite les é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 à tous les 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 aux critères Level et MatchAnyKeyword .

Cette valeur est fréquemment définie sur 0.

[in] EnableProperty

Indicateurs spécifiant des comportements spéciaux que le runtime ETW doit activer lors de la collecte d’événements à partir de ce fournisseur. Pour activer des comportements spéciaux, spécifiez un ou plusieurs des indicateurs suivants. Sinon, définissez EnableProperty sur 0.

Notes

Plusieurs de ces indicateurs indiquent qu’ETW doit inclure des informations supplémentaires dans chaque événement. Les données sont écrites dans la section élément de données étendu de l’événement.

Valeur Signification
EVENT_ENABLE_PROPERTY_SID Incluez l’identificateur de sécurité (SID) de l’utilisateur dans les données étendues.
EVENT_ENABLE_PROPERTY_TS_ID Incluez l’identificateur de session de terminal dans les données étendues.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 La session de suivi ne doit pas enregistrer les événements qui ont un mot clé de 0.

[in, optional] EnableFilterDesc

Une structure EVENT_FILTER_DESCRIPTOR qui pointe vers les données de filtre. Le fournisseur l’utilise pour filtrer les données afin d’empêcher l’écriture d’événements qui ne correspondent pas aux critères de filtre dans la session. Le fournisseur détermine la disposition des données et la façon dont il applique le filtre aux données de l’événement. Une session ne peut passer qu’un seul filtre au fournisseur.

Une session peut appeler la fonction TdhEnumerateProviderFilters pour rechercher les filtres pour lesquels un fournisseur a inscrit la prise en charge.

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 :

    • ProviderId a la valeur NULL.
    • TraceHandle a la valeur NULL.

  • ERROR_INVALID_FUNCTION

    Vous ne pouvez pas mettre à jour le niveau lorsque le fournisseur n’est pas 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.

Dans la plupart des cas, un appel à EnableTraceEx peut être converti en EnableTraceEx2 comme suit :

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

Dans des scénarios plus complexes, un appel à EnableTraceEx peut être converti en EnableTraceEx2 comme suit :

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &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 Vista [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

StartTrace

EnableTraceEx2