Fonction EnableTraceEx2 (evntrace.h)

  • Article

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

Cette fonction remplace les fonctions EnableTrace et EnableTraceEx .

Syntaxe

ULONG WMIAPI EnableTraceEx2(
  [in]           TRACEHANDLE              TraceHandle,
  [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

[in] TraceHandle

Handle de la session de suivi d’événements pour laquelle vous configurez le fournisseur. 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 obtenir le handle à partir du champ Wnode.HistoricalContext des données retournées EVENT_TRACE_PROPERTIES .

[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 Level active le niveau spécifié et tous les niveaux plus graves. 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 mot clé de l’événement correspondent à l’un des bits définis dans cette valeur ou si l’événement n’a aucun mot clé bits 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 mot clé de l’événement correspondent à tous les bits définis dans cette valeur ou si l’événement n’a aucun mot clé bits défini, en plus de répondre aux critères Level et MatchAnyKeyword.

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

[in] Timeout

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

Dans le cas contraire, cette fonction commence à configurer le fournisseur, puis commence à attendre la fin de la configuration, y compris en attendant que tous les rappels du 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 patienter éternellement, 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 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

    Un paramètre est incorrect.

    Cela peut se produire si l’un des éléments suivants est vrai :

    • ProviderId a la valeur NULL.
    • 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 Timeout .

  • 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.

Notes

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.

Le comportement d’activation d’un fournisseur dépend des API que le fournisseur utilise.

  • Un fournisseur qui utilise RegisterTraceGuids (par exemple, un fournisseur utilisant wpP ou MOF basé sur TMF) 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 avertit le fournisseur et fournit l’accès au niveau, aux 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 envoie ces événements 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 et l’ID de message de l’événement, 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, ni niveau ou mot clé informations, ETW ne peut pas effectuer de filtrage ou de routage supplémentaire pour les fournisseurs qui utilisent le système d’activation hérité. Chaque événement ne peut pas être routé vers plus d’une 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 avertit le fournisseur avec le niveau, le masque MatchAnyKeyword 64 bits, le masque MatchAllKeyword 64 bits et toutes 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 d’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 le cas échéant, 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, le cas échéant.

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

  • Filtrage schématisé : il s’agit de la configuration de filtrage traditionnelle, également appelée filtrage côté fournisseur. Le contrôleur définit un ensemble personnalisé de filtres en tant qu’objet binaire passé 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 rapproché du contrôleur et du fournisseur, car le type et le format de l’objet binaire de ce qui peut être filtré ne sont pas définis. 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 sur 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 : avertit ETW d’effectuer une marche de pile uniquement pour un ensemble donné d’ID d’événements ou de noms d’événements (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 manifeste, les événements peuvent être filtrés en fonction d’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 manifeste, 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.

Notes

Même si ETW prend en charge un filtrage puissant de charge utile et d’attributs, les événements doivent principalement être des filtres d’étendue basés sur un filtre ou via un GUID de contrôle, un niveau et un mot clé. Les fournisseurs effectuent généralement un filtrage de GUID de contrôle, de niveau et de mot clé directement dans le code du fournisseur avant que l’événement ne soit généré ou envoyé à ETW. Dans la plupart des fournisseurs, les événements désactivés par niveau ou par mot clé presque aucun impact sur les performances du système. De même, les fournisseurs désactivés par les filtres d’étendue n’ont pratiquement aucun impact sur les performances du système. D’autres types de filtrage (basés sur une charge utile ou des attributs autres que level et mot clé) sont généralement effectués après 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 consacré à la préparation de l’événement et son envoi à 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 n’est efficace que 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 que EnableTraceEx2 est appelé, les filtres du fournisseur dans 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 un seul appel EnableTraceEx2 peuvent être combinés avec un effet additif, mais les filtres passés dans un appel suivant remplaceront l’ensemble de filtres précédent.

Pour désactiver le filtrage et activer ainsi 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 passé dans la structure ENABLE_TRACE_PARAMETERS passée dans le paramètre EnableParameters à la fonction EnableTraceEx2 .

Chaque type de filtre (membre type spécifique) ne peut apparaître qu’une seule fois dans un appel à la fonction EnableTraceEx2 . Certains types de filtres autorisent l’inclusion de 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 futures 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 pouvant contenir plusieurs ID d’application relatifs 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 des catégories d’événements. Par exemple, si le fournisseur définit InitializationKeyword = 0x1 (mot clé bit 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 des événements d’initialisation et de calcul, mais pas des événements de fichier.

Lorsqu’elle est utilisée avec des fournisseurs modernes (basés sur un manifeste ou TraceLogging), une valeur MatchAnyKeyword de 0 est traitée de la même façon qu’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 hérités (MOF ou WPP basés sur TMF). Pour activer tous les mots clés d’événement d’un fournisseur hérité, définissez MatchAnyKeyword sur0xFFFFFFFF. 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, quels que soient les masques MatchAnyKeyword et 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 EnablePropertyd’EnableParameters.

Lorsque vous appelez EnableTraceEx2, le fournisseur est peut-être déjà inscrit ou non. 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 alors à 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 à nouveau EnableTraceEx2 pour mettre à jour les paramètres Level, MatchAnyKeyword, MatchAllKeyword et les membres EnableProperty et EnableFilterDescd’EnableParameters.

Sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures, les filtres de charge utile d’événement, d’étendue et de procédure 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 d’événement, consultez les fonctions TdhCreatePayloadFilter et TdhAggregatePayloadFilters , ainsi que les structures ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR et 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. Elles peuvent uniquement être activées 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, les événements du fournisseur de trace système peuvent être activés à l’aide d’EnableTraceEx2.

Jusqu’à huit sessions de suivi 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 hérité (MOF, WPP basé sur TMF). Si plusieurs sessions tentent 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é, puis 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 :

  • fournisseur de requêtes logman nom _fournisseur
  • wevtutil gp provider-name

Pour les fournisseurs classiques, il incombe au fournisseur de documenter et de mettre à la disposition des contrôleurs potentiels les niveaux de gravité ou les indicateurs d’activation qu’il prend en charge. Si le fournisseur souhaite être activé par un contrôleur, il doit accepter 0 pour le niveau de gravité et activer les indicateurs et interpréter 0 comme une demande d’exécution de la journalisation par défaut (quelle qu’elle soit).

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

  • Le paramètre Level est identique à la définition du paramètre EnableLevel dans EnableTrace.
  • MatchAnyKeyword est identique à la définition du paramètre EnableFlag dans EnableTrace, sauf que la valeur mot clé est tronquée d’une valeur 64 bits à une valeur de 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 illustre l’utilisation de EnableTraceEx2 avec des filtres de charge utile à l’aide des fonctions 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;
}

Spécifications

   
Client minimal pris en charge Windows 7 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2008 R2 [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 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