Fonction EnableTraceEx2 (evntrace.h)

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

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

Gérez 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 du 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 au fournisseur d’enregistrer 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 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 écrire par le fournisseur. 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] 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 démarre la configuration du fournisseur, puis commence à attendre la fin de la configuration, y compris l’attente de tous les rappels de fournisseur. 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 indéfiniment, définissez 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 trace qui peuvent activer le fournisseur.

  • ERROR_ACCESS_DENIED

    Seuls les utilisateurs disposant de privilèges d’administration, d’utilisateurs du Performance Log Users groupe et de services qui s’exécutent en tant que 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-les 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 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 à partir 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 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, 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 envoie 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 effectuer aucun filtrage ou routage supplémentaire 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 avertit 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éterminer quels événements doivent être activés, bien que la plupart des fournisseurs dupliquent 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 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, le cas échéant.

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. (Pour plus d’informations, consultez EVENT_FILTER_DESCRIPTOR .)

  • 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 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 De filtreEventWriteEx 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 avertit ETW d’effectuer uniquement une procédure de pile pour un ensemble donné d’ID d’événement ou (pour les événements TraceLogging) des noms d’événements. Cette fonctionnalité est prise en charge sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
  • Filtrage des attributs : pour les fournisseurs de manifeste, 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 manifeste, les événements peuvent être filtrés à la volée en fonction du fait 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 le filtrage de charges utiles et d’attributs puissants, 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 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 transmis à la fonction EnableTraceEx2 . Plusieurs filtres transmis dans un seul appel EnableTraceEx2 peuvent être combinés avec un effet additif, mais les filtres passés dans un appel suivant remplacent l’ensemble précédent de filtres.

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 de type spécifique) peut apparaître une seule fois dans un appel à la fonction EnableTraceEx2 . Certains types de filtres permettent à plusieurs conditions d’être incluses 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 de type spécifique de 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 qui peut 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 des catégories d’événements. Par exemple, si le fournisseur définit InitializationKeyword = 0x1 (mot clé 0), FileOperationKeyword = 0x2 (mot clé 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’ils sont utilisés avec des fournisseurs modernes (basés sur un manifeste ou TraceLogging), une valeur MatchAnyKeyword est 0 traitée comme une valeur MatchAnyKeyword de 0xFFFFFFFFFFFFFFFF, c’est-à-dire active tous les mots clés d’événement. Toutefois, ce comportement ne s’applique pas aux fournisseurs WPP (MOF ou TMF) hérités. 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 masque 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 EnableProperty d’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 à 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 à nouveau pour mettre à jour le niveau, MatchAnyKeyword, les paramètres MatchAllKeyword et les membres EnableProperty et EnableFilterDescd’EnableParameters.

Sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures, la charge utile des événements, l’étendue et les filtres 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énements, consultez les fonctions TdhCreatePayloadFilter et TdhAggregatePayloadFilters et les fonctions ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR et PAYLOAD_FILTER_PREDICATE structures.

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.

À partir de Windows 11, les é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) hérité. 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 :

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

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 comme une demande pour effectuer la journalisation par défaut (ce qui peut être).

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

  • Le paramètre Level est identique au paramètre EnableLevel dans EnableTrace.
  • 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 de enableTraceEx2 avec des filtres de charge utile à l’aide de TdhCreatePayloadFilter et de 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;
}

Configuration requise

   
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