traceloggingprovider.h, en-tête

TraceLogging est un système permettant de journaliser des événements auto-décrivant qui peuvent être décodés sans manifeste. Sur Windows, TraceLogging est utilisé pour générer des événements de suivi d’événements pour Windows (ETW ).

L’en-tête TraceLoggingProvider.h dans le Kit de développement logiciel (SDK) Windows contient des macros et des fonctions inline pour générer des événements ETW encodés par TraceLogging pour le code en mode noyau et en mode utilisateur à l’aide de C ou C++.

Notes

TraceLoggingProvider.h nécessite des valeurs constantes au moment de la compilation pour les attributs d’événement tels que le nom du fournisseur, le nom de l’événement et les noms de champs. Pour réduire la surcharge d’exécution, TraceLoggingProvider.h génère ses structures de données au moment de la compilation et stocke les informations en mémoire en lecture seule. Si vous devez générer des événements dynamiques d’exécution, vous devez utiliser une autre implémentation TraceLogging, telle que TraceLoggingDynamic.

Démarrage rapide

• Dans un fichier .c ou .cpp, utilisez la macro TRACELOGGING_DEFINE_PROVIDER pour déclarer un handle de fournisseur global. Le handle du fournisseur représente la connexion de votre composant à ETW.
• Au démarrage du composant (par exemple, dans main, wmain, DllMainou DriverEntry), utilisez la fonction TraceLoggingRegister pour ouvrir la connexion de votre composant à ETW.
• À l’arrêt du composant, utilisez la fonction TraceLoggingUnregister pour fermer la connexion de votre composant à ETW.
• Pendant l’exécution du composant, utilisez la macro TraceLoggingWrite pour générer des événements ETW encodés par TraceLogging.
• Si nécessaire, utilisez la macro TRACELOGGING_DECLARE_PROVIDER dans les en-têtes pour transférer-déclarer le handle du fournisseur afin qu’il puisse être utilisé dans d’autres parties de votre composant.
• Utilisez des outils tels que WPR, tracelog ou traceview pour collecter des traces.
• Utilisez des outils tels que WPA, tracefmt ou traceview pour décoder et afficher les traces.

Exemple

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider, // Name of the provider handle
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Pour plus d'informations, consultez les pages suivantes :

• TraceLogging
• Macros du wrapper TraceLogging
• TraceLoggingWrite
• TRACELOGGING_DECLARE_PROVIDER
• TRACELOGGING_DEFINE_PROVIDER

traceloggingprovider.h contient les interfaces de programmation suivantes :

Fonctions

TRACELOGGING_DECLARE_PROVIDER Déclare un handle pour un fournisseur TraceLogging.
TRACELOGGING_DEFINE_PROVIDER Définit un handle pour un fournisseur TraceLogging.
TRACELOGGING_DEFINE_PROVIDER_STORAGE Réserve le stockage statique pour un handle de fournisseur TraceLogging qui sera défini par l’utilisateur. Préférez TRACELOGGING_DEFINE_PROVIDER à cette macro.
TraceLoggingBinary Macro wrapper TraceLogging qui ajoute un champ avec des données binaires à l’événement.
TraceLoggingChannel Macro wrapper TraceLogging qui définit le canal de l’événement.
TraceLoggingCustom Macro wrapper TraceLogging qui ajoute à l’événement un champ qui a été empaqueté à l’aide d’un sérialiseur personnalisé.
TraceLoggingCustomAttribute Macro wrapper TraceLogging qui ajoute des informations personnalisées sur l’événement dans le PDB.
TraceLoggingDescription Macro wrapper TraceLogging qui définit la description de l’événement.
TraceLoggingEventTag Macro wrapper TraceLogging qui définit la balise d’événement pour l’événement.
TraceLoggingKeyword Macro wrapper TraceLogging qui définit le mot clé de l’événement.
TraceLoggingLevel Macro wrapper TraceLogging qui définit le niveau de l’événement
TraceLoggingOpcode Macro wrapper TraceLogging qui définit l’opcode pour l’événement
TraceLoggingOptionGroup Macro TraceLogging à utiliser dans TRACELOGGING_DEFINE_PROVIDER pour spécifier un groupe de fournisseurs.
TraceLoggingProviderEnabled Macro TraceLogging pour déterminer si un consommateur de trace écoute un événement de ce fournisseur.
TraceLoggingProviderId Obtient l’ID de fournisseur d’un fournisseur TraceLogging.
TraceLoggingRegister Inscrit un fournisseur TraceLogging afin qu’il puisse être utilisé pour journaliser des événements.
TraceLoggingRegisterEx Inscrit un fournisseur TraceLogging afin qu’il puisse être utilisé pour journaliser des événements, en spécifiant un rappel d’activation ETW.
TraceLoggingSetInformation Configure un fournisseur TraceLogging en appelant EventSetInformation.
TraceLoggingSocketAddress Macro wrapper TraceLogging qui ajoute un champ avec une adresse de socket à l’événement.
TraceLoggingStruct Macro wrapper TraceLogging qui ajoute un champ qui contient d’autres champs à l’événement.
TraceLoggingUnregister Annule l’inscription d’un fournisseur TraceLogging.
TraceLoggingValue Macro wrapper TraceLogging pour C++ qui ajoute un champ avec un type déduit automatiquement à l’événement.
TraceLoggingWrite Émet un événement TraceLogging.
TraceLoggingWriteActivity Émet un événement TraceLogging avec des ID d’activité spécifiés.