EnableTraceEx2, fonction (evntrace.h)

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

Cette fonction remplace les fonctions EnableTrace et EnableTraceEx.

Syntaxe

ULONG WMIAPI EnableTraceEx2(
                 CONTROLTRACE_ID          TraceId,
  [in]           LPCGUID                  ProviderId,
  [in]           ULONG                    ControlCode,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    Timeout,
  [in, optional] PENABLE_TRACE_PARAMETERS EnableParameters
);

Paramètres

TraceId

[in] ProviderId

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

[in] ControlCode

Vous pouvez spécifier l’un des codes de contrôle suivants :

Valeur	Signification
EVENT_CONTROL_CODE_DISABLE_PROVIDER	Mettez à jour la configuration de session afin que la session ne reçoive pas d’événements du fournisseur.
EVENT_CONTROL_CODE_ENABLE_PROVIDER	Mettez à jour la configuration de session afin que la session reçoive les événements demandés du fournisseur.
EVENT_CONTROL_CODE_CAPTURE_STATE	Demande que le fournisseur consigne ses informations d’état.

[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 de niveau active le niveau spécifié et tous les niveaux plus graves. Par exemple, si vous spécifiez TRACE_LEVEL_WARNING, votre consommateur reçoit des avertissements, des erreurs et des événements critiques.

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

Les constantes TRACE_LEVEL sont définies dans evntrace.h. Les constantes WINMETA_LEVEL équivalentes 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 écrire par le fournisseur. Le fournisseur écrit généralement un événement si les bits de mot clé de l’événement correspondent toute des bits définis dans cette valeur ou si l’événement n’a pas de bits de mot clé définis, en plus de répondre aux niveau et MatchAllKeyword critères.

[in] MatchAllKeyword

Masque de bits 64 bits de mots clés qui restreint 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 toutes les des bits définis dans cette valeur ou si l’événement n’a pas de bits de mot clé définis, en plus de répondre aux niveau et MatchAnyKeyword critères.

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

[in] Timeout

Si délai d’expiration est 0, cette fonction commence à configurer le fournisseur de façon asynchrone et retourne immédiatement (c’est-à-dire qu’elle retourne sans attendre que les rappels de fournisseur se terminent).

Dans le cas contraire, cette fonction démarre la configuration du fournisseur, puis commence à attendre la fin de la configuration, y compris en attendant que tous les rappels de fournisseur se terminent. Si la configuration se termine avant le délai d’expiration spécifié, cette fonction retourne ERROR_SUCCESS. Sinon, cette fonction retourne ERROR_TIMEOUT.

Pour attendre toujours, définissez sur INFINITE.

[in, optional] EnableParameters

Paramètres de trace utilisés pour activer le fournisseur. Pour plus d’informations, consultez ENABLE_TRACE_PARAMETERS.

Valeur de retour

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

  Un paramètre est incorrect.

  Cela peut se produire si l’une des valeurs suivantes est true :

  • Le ProviderId est NULL.
  • Le TraceHandle est 0.

• ERROR_TIMEOUT

  La valeur du délai d’expiration a expiré avant la fin du rappel d’activation. Pour plus d’informations, consultez le paramètre Délai d’expiration.

• 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 qui peuvent activer le fournisseur.

• ERROR_ACCESS_DENIED

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

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

Remarques

Les contrôleurs de trace 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 à partir d’un fournisseur, ou pour arrêter la collecte d’événements auprès d’un fournisseur.

Le comportement d’activation d’un fournisseur dépend des API utilisées par le fournisseur.

• Un fournisseur qui utilise RegisterTraceGuids (par exemple, un fournisseur utilisant TMF WPP ou MOF) utilise le système d’activation hérité (parfois appelé « ETW classique »). Lorsqu’un fournisseur hérité est activé ou reconfiguré pour une session, le runtime ETW notifie le fournisseur et fournit l’accès au niveau, les 32 bits faibles du masque MatchAnyKeyword et l’ID de session. Le fournisseur utilise ensuite sa propre logique pour décider quels événements doivent être activés et les envoyer directement à la session spécifiée. Les données d’événement envoyées à ETW au moment de l’exécution incluent le GUID de décodage de l’événement et l’ID de message, mais n’incluent pas le GUID de contrôle, le niveau ou les mots clés de l’événement. ETW vérifie que le fournisseur dispose des autorisations nécessaires, puis ajoute les données d’événement à la session spécifiée.
  • Étant donné que les événements sont envoyés directement à une session spécifique sans GUID de contrôle, niveau ou informations de mot clé, ETW ne peut pas effectuer de filtrage ou de routage supplémentaires pour les fournisseurs qui utilisent le système d’activation hérité. Chaque événement peut être routé vers aucune session.
• Un fournisseur qui utilise EventRegister (par exemple, un fournisseur basé sur un manifeste ou un fournisseur TraceLogging) utilise le système d’activation moderne (parfois appelé « crimson ETW »). Lorsqu’un fournisseur moderne est activé ou reconfiguré pour une session, le runtime ETW notifie le fournisseur avec le niveau, le masque MatchAnyKeyword 64 bits, le masque MatchAllKeyword 64 bits et les données de filtrage personnalisées côté fournisseur spécifiées par le contrôleur de trace. Le fournisseur utilise ensuite sa propre logique pour décider quels événements doivent être activés, bien que la plupart des fournisseurs dupliquez simplement la logique de EventProviderEnabled. Le fournisseur envoie les événements activés à ETW pour le routage. Les données d’événement envoyées à ETW incluent le GUID de contrôle de l’événement, l’ID de message, le niveau et les mots clés. ETW effectue ensuite un filtrage supplémentaire selon les besoins, en acheminant l’événement vers la ou les sessions appropriées.
  • Étant donné que les événements sont envoyés à ETW avec des informations descriptives, ETW peut effectuer un filtrage et un routage supplémentaires avant d’ajouter l’événement à la session. Les événements peuvent être routés vers plusieurs sessions si nécessaire.

Pour les fournisseurs qui utilisent le système d’activation moderne (c’est-à-dire les fournisseurs utilisant EventRegister), ETW prend en charge plusieurs fonctionnalités qui peuvent être demandées par le contrôleur de session de trace via EnableTraceEx2EnableParameters. (Consultez EVENT_FILTER_DESCRIPTOR pour plus d’informations.)

• de filtrage schématisé : il s’agit de la configuration traditionnelle du filtrage, également appelée filtrage côté fournisseur. Le contrôleur définit un ensemble personnalisé de filtres en tant qu’objet binaire transmis au fournisseur dans EnableCallbackFilterData. Il incombe au contrôleur et au fournisseur de définir et d’interpréter ces filtres. Le fournisseur peut ensuite utiliser le paramètre EventWriteExFilter pour indiquer les sessions auxquelles un événement ne doit pas être envoyé en raison du filtrage côté fournisseur. Cela nécessite un couplage étroit du contrôleur et du fournisseur, car le type et le format de l’objet binaire de ce qui peut être filtré n’est pas défini. La fonction TdhEnumerateProviderFilters peut être utilisée pour récupérer les filtres définis dans un manifeste.
• filtrage d’étendue : certains fournisseurs sont activés ou non activés pour une session selon qu’ils répondent ou non aux critères spécifiés par les filtres d’étendue. Il existe plusieurs types de filtres d’étendue qui autorisent le filtrage en fonction de l’ID de processus (PID), du nom de fichier exécutable, de l’ID d’application et du nom du package d’application. Cette fonctionnalité est prise en charge sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
• filtrage Stackwalk : cela informe ETW d’effectuer uniquement une procédure de pile pour un ensemble donné d’ID d’événement ou (pour les événements TraceLogging). Cette fonctionnalité est prise en charge sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
• filtrage d’attributs : pour les fournisseurs de manifestes, les événements peuvent être filtrés en fonction des attributs d’événement tels que le niveau, le mot clé, l’ID d’événement ou le nom de l’événement.
• filtrage de charge utile d’événement : pour les fournisseurs de manifestes, les événements peuvent être filtrés à la volée selon qu’ils répondent ou non à une expression logique basée sur un ou plusieurs prédicats.

Note

Même si ETW prend en charge un filtrage puissant de charge utile et d’attribut, les événements doivent principalement être filtrés en fonction des filtres d’étendue ou via le GUID de contrôle, le niveau et le mot clé. Les fournisseurs effectuent généralement un guid de contrôle, un niveau et un filtrage de mots clés directement dans le code du fournisseur avant que l’événement soit généré ou envoyé à ETW. Dans la plupart des fournisseurs, les événements désactivés par niveau ou mot clé n’ont presque aucun impact sur les performances du système. De même, les fournisseurs désactivés par les filtres d’étendue n’ont presque aucun impact sur les performances du système. D’autres types de filtrage (basés sur la charge utile ou les attributs autres que le niveau et le mot clé) sont généralement effectués une fois que le fournisseur a généré l’événement et l’a envoyé au runtime ETW, ce qui signifie que l’événement a un impact sur les performances du système (le temps processeur passé à préparer l’événement et à l’envoyer à ETW), même si le filtrage ETW détermine que l’événement ne doit pas être enregistré par des sessions. Ce type de filtrage est efficace uniquement pour réduire le volume de données de trace et n’est pas aussi efficace pour réduire la surcharge du processeur de trace.

Chaque fois EnableTraceEx2 est appelée, les filtres du fournisseur de cette session sont remplacés par les nouveaux paramètres définis par les paramètres passés à la fonction EnableTraceEx2. Plusieurs filtres passés dans une seule l’appel d’enableTraceEx2 peuvent être combinés avec un effet additif, mais les filtres passés dans un appel ultérieur remplacent l’ensemble précédent de filtres.

Pour désactiver le filtrage et ainsi activer tous les fournisseurs/événements dans la session de journalisation, appelez EnableTraceEx2 avec le paramètre EnableParameters pointant vers une structure ENABLE_TRACE_PARAMETERS avec le membre FilterDescCount défini sur 0.

Chaque filtre passé à la fonction EnableTraceEx2 est spécifié par un membre Type dans le EVENT_FILTER_DESCRIPTOR. Un tableau de structures EVENT_FILTER_DESCRIPTOR est transmis dans la structure ENABLE_TRACE_PARAMETERS passée dans le paramètre EnableParameters à la fonction EnableTraceEx2.

Chaque type de filtre (un type spécifique membre) ne peut apparaître qu’une seule fois dans un appel à la fonction EnableTraceEx2. Certains types de filtres permettent d’inclure plusieurs conditions dans un seul filtre. Le nombre maximal de filtres pouvant être inclus dans un appel à EnableTraceEx2 est défini par MAX_EVENT_FILTERS_COUNT (défini dans le fichier d’en-tête evntprov.h  ; la valeur peut changer dans les versions ultérieures du Kit de développement logiciel (SDK) Windows).

Chaque type de filtre a ses propres limites de taille ou d’entité en fonction du membre type spécifique dans la structure EVENT_FILTER_DESCRIPTOR. La liste ci-dessous indique ces limites.

• EVENT_FILTER_TYPE_SCHEMATIZED

  • Limite de taille de filtre : MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Nombre d’éléments autorisés : défini par le fournisseur et le contrôleur

• EVENT_FILTER_TYPE_PID

  • Limite de taille de filtre : MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Nombre d’éléments autorisés : MAX_EVENT_FILTER_PID_COUNT (8)

• EVENT_FILTER_TYPE_EXECUTABLE_NAME

  • Limite de taille de filtre : MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Nombre d’éléments autorisés : chaîne unique pouvant contenir plusieurs noms de fichiers exécutables séparés par des points-virgules.

• EVENT_FILTER_TYPE_PACKAGE_ID

  • Limite de taille de filtre : MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Nombre d’éléments autorisés : chaîne unique pouvant contenir plusieurs ID de package séparés par des points-virgules.

• EVENT_FILTER_TYPE_PACKAGE_APP_ID

  • Limite de taille de filtre : MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Nombre d’éléments autorisés : chaîne unique qui peut contenir plusieurs ID d’application relative de package (PRAID) séparés par des points-virgules.

• EVENT_FILTER_TYPE_PAYLOAD

  • Limite de taille de filtre : MAX_EVENT_FILTER_PAYLOAD_SIZE (4096)
  • Nombre d’éléments autorisés : 1

• EVENT_FILTER_TYPE_EVENT_ID

  • Limite de taille de filtre : non définie
  • Nombre d’éléments autorisés : MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

• EVENT_FILTER_TYPE_STACKWALK

  • Limite de taille de filtre : non définie
  • Nombre d’éléments autorisés : MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

Les mots clés définissent les catégories d’événements. Par exemple, si le fournisseur définit InitializationKeyword = 0x1 (bit de mot clé 0), FileOperationKeyword = 0x2 (mot clé bit 1) et CalculationKeyword = 0x4 (mot clé bit 2), vous pouvez définir MatchAnyKeyword sur (InitializationKeyword | CalculationKeyword) = 5 pour recevoir les événements d’initialisation et de calcul, mais pas les événements de fichier.

Lorsqu’elles sont utilisées avec des fournisseurs modernes ( ou TraceLogging), une valeur MatchAnyKeyword de 0 est traitée comme une valeur MatchAnyKeyword de 0xFFFFFFFFFFFFFFFF, c’est-à-dire qu’elle active tous les mots clés d’événement. Toutefois, ce comportement ne s’applique pas aux fournisseurs WPP hérités (MOF ou TMF). Pour activer tous les mots clés d’événement d’un fournisseur hérité, définissez MatchAnyKeyword sur 0xFFFFFFFF. Pour activer tous les mots clés d’événement des fournisseurs hérités et modernes, définissez MatchAnyKeyword sur 0xFFFFFFFFFFFFFFFF.

Si le mot clé d’un événement est égal à zéro, le fournisseur écrit l’événement dans la session, quel que soit le MatchAnyKeyword et Masque MatchAllKeyword. (Ce comportement peut être désactivé à l’aide de l’indicateur EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0.)

Pour indiquer que vous souhaitez activer un groupe de fournisseurs, utilisez l’indicateur EVENT_ENABLE_PROPERTY_PROVIDER_GROUP sur le membre EnableProperty de EnableParameters.

Lorsque vous appelez EnableTraceEx2, le fournisseur peut ou non déjà être inscrit. Si le fournisseur est déjà inscrit, ETW appelle la fonction de rappel du fournisseur (le cas échéant) et la session commence à recevoir des événements. Si le fournisseur n’est pas déjà inscrit, ETW appelle la fonction de rappel du fournisseur (le cas échéant) immédiatement après l’inscription du fournisseur et la session commence ensuite à recevoir des événements. Si le fournisseur n’est pas déjà inscrit, la fonction de rappel du fournisseur ne reçoit pas l’ID source.

Si le fournisseur est inscrit et déjà activé pour votre session, vous pouvez appeler EnableTraceEx2 de nouveau pour mettre à jour lede niveau , MatchAnyKeyword, paramètres MatchAllKeyword et les paramètres EnableProperty et EnableFilterDesc membres de EnableParameters.

Sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures, les filtres de procédure d’événement, d’étendue et de pile peuvent être utilisés par la fonction EnableTraceEx2 et les structures ENABLE_TRACE_PARAMETERS et EVENT_FILTER_DESCRIPTOR pour filtrer sur des conditions spécifiques dans une session d’enregistreur d’événements. Pour plus d’informations sur les filtres de charge utile des événements, consultez les fonctions TdhCreatePayloadFilteret TdhAggregatePayloadFilters fonctions et les structures ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTORet PAYLOAD_FILTER_PREDICATE.

Les événements de fournisseur de trace système spéciaux ne peuvent pas être activés ou désactivés par EnableTraceEx2. Ils ne peuvent être activés que via le champ EnableFlags de EVENT_TRACE_PROPERTIES lorsque la trace est démarrée pour la première fois par StartTrace.

À compter de Windows 11, événements du fournisseur de trace système peuvent être activés à l’aide d’EnableTraceEx2.

Jusqu’à huit sessions de trace peuvent activer et recevoir des événements du même fournisseur moderne ( basé sur un manifeste ou TraceLogging). Toutefois, une seule session de trace peut activer un fournisseur WPP (MOF, TMF). Si plusieurs sessions essaient d’activer un fournisseur hérité, la première session cesse de recevoir des événements lorsque la deuxième session active le même fournisseur. Par exemple, si la session A a activé un fournisseur hérité et que la session B a activé le même fournisseur, seule la session B reçoit des événements de ce fournisseur.

Un fournisseur reste activé pour la session jusqu’à ce que la session désactive le fournisseur. Si l’application qui a démarré la session se termine sans désactiver le fournisseur, le fournisseur reste activé.

Pour déterminer le niveau et les mots clés utilisés pour activer un fournisseur basé sur un manifeste, utilisez l’une des commandes suivantes :

• fournisseurs de requêtes logman nom du fournisseur
• wevtutil gp nom du fournisseur

Pour les fournisseurs classiques, il incombe au fournisseur de documenter et de mettre à la disposition des contrôleurs potentiels les niveaux de gravité ou d’activer les indicateurs qu’il prend en charge. Si le fournisseur souhaite être activé par n’importe quel contrôleur, le fournisseur doit accepter 0 pour le niveau de gravité et activer les indicateurs et interpréter 0 en tant que demande d’exécution de journalisation par défaut (ce qui peut être le cas).

Si vous utilisez enableTraceEx2 pour activer un fournisseur classique, la traduction suivante se produit :

• Le paramètre niveau de est identique à la définition du paramètre EnableLevel dans EnableTrace.
• Le MatchAnyKeyword est identique à la définition du paramètre EnableFlag dans EnableTrace sauf que la valeur du mot clé est tronquée d’une valeur 64 bits à une valeur 32 bits.
• Dans le rappel ControlCallback, le fournisseur peut appeler GetTraceEnableLevel pour obtenir le niveau et GetTraceEnableFlags pour obtenir l’indicateur d’activation.
• L’autre paramètre n’est pas utilisé.

Exemples

L’exemple suivant montre l’utilisation du EnableTraceEx2 avec des filtres de charge utile à l’aide des filtres de charge utile TdhCreatePayloadFilter et TdhAggregatePayloadFilters pour filtrer sur des conditions spécifiques dans une session d’enregistreur d’événements.

#define INITGUID
#include <windows.h>
#include <stdlib.h>
#include <stdio.h>
#include <strsafe.h>
#include <evntrace.h>
#include <tdh.h>

#define MAXIMUM_SESSION_NAME 1024

#define PATH_TO_MANIFEST_FILE L"c:\\ExampleManifest.man"

//
// The following definitions would be found in the include file generated by
// message compiler from the manifest file.
//

// Provider Example-Provider Event Count 2
EXTERN_C __declspec(selectany) const GUID EXAMPLE_PROVIDER = {0x37a59b93, 0xbb25, 0x4cee, {0x97, 0xaa, 0x8b, 0x6a, 0xcd, 0xc, 0x4d, 0xf8}};

//
// Event Descriptors
//
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_1 = { 0x1, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_1_value 0x1
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_2 = { 0x2, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_2_value 0x2

//
// (End of snippet from include file)
//

// Allocate an EVENT_TRACE_PROPERTIES structure and set the needed logging session properties
PEVENT_TRACE_PROPERTIES AllocateTraceProperties(
    _In_opt_ PCWSTR LoggerName,
    _In_opt_ PCWSTR LogFileName
)
{
    PEVENT_TRACE_PROPERTIES TraceProperties = NULL;
    ULONG BufferSize;

    BufferSize = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME + MAX_PATH) * sizeof(WCHAR);

    TraceProperties = (PEVENT_TRACE_PROPERTIES)malloc(BufferSize);
    if (TraceProperties == NULL) {
        printf("Unable to allocate %d bytes for properties structure.\n", BufferSize);
        goto Exit;
    }

    //
    // Set the session properties.
    //
    ZeroMemory(TraceProperties, BufferSize);
    TraceProperties->Wnode.BufferSize = BufferSize;
    TraceProperties->Wnode.Flags = WNODE_FLAG_TRACED_GUID;
    TraceProperties->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
    TraceProperties->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME * sizeof(WCHAR));

    if (LoggerName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LoggerNameOffset),
            MAXIMUM_SESSION_NAME,
            LoggerName);
    }

    if (LogFileName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LogFileNameOffset),
            MAX_PATH,
            LogFileName);
    }

Exit:
    return TraceProperties;
}

// Free the EVENT_TRACE_PROPERTIES structure previously allocated
VOID FreeTraceProperties(
    _In_ PEVENT_TRACE_PROPERTIES TraceProperties
)
{
    free(TraceProperties);
    return;
}

// Set the values needed in a PAYLOAD_FILTER_PREDICATE for a single payload filter
FORCEINLINE VOID PayloadPredicateCreate(
    _Out_ PAYLOAD_FILTER_PREDICATE* Predicate,
    _In_ PCWSTR FieldName,
    USHORT CompareOp,
    PCWSTR Value
)
{
    Predicate->FieldName = (PWSTR)FieldName;
    Predicate->CompareOp = CompareOp;
    Predicate->Value = (PWSTR)Value;
    return;
}

int __cdecl wmain()
{
    UINT i;
    PVOID EventFilters[2];
    EVENT_FILTER_DESCRIPTOR FilterDescriptor;
    UINT PredicateCount;
    PAYLOAD_FILTER_PREDICATE Predicates[3];
    ULONG FilterCount;
    ULONG Status = ERROR_SUCCESS;
    TRACEHANDLE SessionHandle = 0;
    PEVENT_TRACE_PROPERTIES TraceProperties;
    BOOLEAN TraceStarted = FALSE;
    PCWSTR LoggerName = L"MyTrace";
    ENABLE_TRACE_PARAMETERS EnableParameters;

    ZeroMemory(EventFilters, sizeof(EventFilters));
    ZeroMemory(Predicates, sizeof(Predicates));
    TraceProperties = NULL;
    FilterCount = 0;

    //
    // Load the manifest for the provider
    //
    Status = TdhLoadManifest((PWSTR)PATH_TO_MANIFEST_FILE);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    //
    // INCLUDE Example_Event_1 IF
    //     Example_Event_1.Initiator == "User" AND
    //     7 <= Example_Event_1.Level <= 16
    //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        (PWSTR)L"Initiator",
        PAYLOADFIELD_IS,
        (PWSTR)L"User");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Level",
        PAYLOADFIELD_BETWEEN,
        L"7,16");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_1,
        FALSE,      // Match all predicates (AND)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    // INCLUDE Example_Event_2 IF
    //      Example_Event_2.Title CONTAINS "UNI" OR
    //      Example_Event_2.InstanceId == {0E95CFBC-58D4-44BA-BE40-E63A853536DF} OR
    //      Example_Event_2.ErrorCode != 0      //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Title",
        PAYLOADFIELD_CONTAINS,
        L"UNI");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"InstanceId",
        PAYLOADFIELD_IS,
        L" {0E95CFBC-58D4-44BA-BE40-E63A853536DF}");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"ErrorCode",
        PAYLOADFIELD_NE,
        L"0");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_2,
        FALSE,      // Match any predicates (OR)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Combine the interim filters into a final filter descriptor.
    //
    Status = TdhAggregatePayloadFilters(
        FilterCount,
        EventFilters,
        NULL,
        &FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhAggregatePayloadFilters() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the interim filters
    //
    for (i = 0; i < FilterCount; i++) {

        Status = TdhDeletePayloadFilter(&EventFilters[i]);
        if (Status != ERROR_SUCCESS) {
            printf("TdhDeletePayloadFilter() failed with %lu\n", Status);
            goto Exit;
        }
    }

    //
    // Create a new trace session
    //
    //
    // Allocate EVENT_TRACE_PROPERTIES structure and perform some
    // basic initialization.
    //
    // N.B. LoggerName will be populated during StartTrace call.
    //
    TraceProperties = AllocateTraceProperties(NULL, L"SystemTrace.etl");
    if (TraceProperties == NULL) {
        Status = ERROR_OUTOFMEMORY;
        goto Exit;
    }

    TraceProperties->LogFileMode = EVENT_TRACE_FILE_MODE_SEQUENTIAL | EVENT_TRACE_SYSTEM_LOGGER_MODE;
    TraceProperties->MaximumFileSize = 100; // Limit file size to 100MB max
    TraceProperties->BufferSize = 512; // Use 512KB trace buffers
    TraceProperties->MinimumBuffers = 8;
    TraceProperties->MaximumBuffers = 64;

    Status = StartTraceW(&SessionHandle, LoggerName, TraceProperties);
    if (Status != ERROR_SUCCESS) {
        printf("StartTrace() failed with %lu\n", Status);
        goto Exit;
    }

    TraceStarted = TRUE;

    //
    // Enable the provider to a trace session with filtering enabled on the
    // provider
    //
    ZeroMemory(&EnableParameters, sizeof(EnableParameters));
    EnableParameters.Version = ENABLE_TRACE_PARAMETERS_VERSION_2;
    EnableParameters.EnableFilterDesc = &FilterDescriptor;
    EnableParameters.FilterDescCount = 1;

    Status = EnableTraceEx2(
        SessionHandle,
        &EXAMPLE_PROVIDER,
        EVENT_CONTROL_CODE_ENABLE_PROVIDER,
        TRACE_LEVEL_VERBOSE,
        0,
        0,
        0,
        &EnableParameters);
    if (Status != ERROR_SUCCESS) {
        printf("EnableTraceEx2() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the payload descriptor
    //
    Status = TdhCleanupPayloadEventFilterDescriptor(&FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCleanupPayloadEventFilterDescriptor() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Collect trace for 30 seconds
    //
    Sleep(30 * 1000);

Exit:

    //
    // Stop tracing.
    //
    if (TraceStarted != FALSE) {
        Status = ControlTraceW(SessionHandle, NULL, TraceProperties, EVENT_TRACE_CONTROL_STOP);
        if (Status != ERROR_SUCCESS) {
            printf("StopTrace() failed with %lu\n", Status);
        }
    }

    if (TraceProperties != NULL) {
        FreeTraceProperties(TraceProperties);
    }

    TdhUnloadManifest((PWSTR)PATH_TO_MANIFEST_FILE);

    return Status;
}

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 7 [applications de bureau | Applications UWP]
serveur minimum pris en charge	Windows Server 2008 R2 [applications de bureau | Applications UWP]
plateforme cible	Windows
d’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 et Windows Server 2008 R2
DLL	Sechost.dll sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.dll sur Windows 8, Windows Server 2012, Windows 7 et Windows Server 2008 R2

Voir aussi

StartTrace

ControlTrace

enableCallback

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_DESCRIPTOR