TRACELOGGING_DEFINE_PROVIDER macro (traceloggingprovider.h)

Article
03/13/2024

Définit un handle pour un fournisseur TraceLogging.

Syntaxe

void TRACELOGGING_DEFINE_PROVIDER(
  [in]            handleVariable,
  [in]            providerName,
  [in]            providerId,
  [in, optional]  __VA_ARGS__
);

Paramètres

[in] handleVariable

Nom à utiliser pour le handle du fournisseur, en utilisant les conventions d’affectation de noms de votre composant pour les variables globales, par exemple MyComponentLog ou g_hMyProvider.

[in] providerName

Littéral de chaîne portant le nom du fournisseur TraceLogging. Ce nom doit être spécifique à votre organization et à votre composant afin qu’il n’entre pas en conflit avec les fournisseurs d’autres composants. Cette chaîne de nom étant incluse dans chaque événement ETW généré par le fournisseur, essayez d’utiliser un nom relativement court. Par exemple, vous pouvez utiliser un nom comme "MyCompany.MyComponent" ou "MyCompany.MyOrganization.MyComponent".

Il doit s’agir d’un littéral de chaîne. N’utilisez pas de variable.

[in] providerId

GUID de contrôle ETW pour le fournisseur, spécifié sous la forme d’une liste séparée par des virgules de 11 entiers entre parenthèses. Par exemple, le GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} est exprimé sous la forme (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).

Bien que n’importe quel GUID unique puisse être utilisé pour l’ID de fournisseur, Microsoft recommande d’utiliser un GUID généré à partir du nom du fournisseur à l’aide de l’algorithme de hachage de nom ETW. Voir ci-dessous pour plus d’informations sur la génération de l’ID de fournisseur.

[in, optional] __VA_ARGS__

Paramètres facultatifs pour le fournisseur. La plupart des fournisseurs n’ont pas besoin de spécifier de paramètres facultatifs.

Si vous souhaitez que votre fournisseur soit associé à un groupe de fournisseurs ETW, ajoutez la macro TraceLoggingOptionGroup pour spécifier le GUID du groupe du fournisseur. Sinon, ne spécifiez aucun __VA_ARGS__ paramètre.

Valeur de retour

None

Remarques

Un fournisseur TraceLogging est une connexion par laquelle les événements peuvent être envoyés à ETW. La TRACELOGGING_DEFINE_PROVIDER macro définit un fournisseur TraceLogging et crée un handle qui peut être utilisé pour y accéder. Il enregistre également des informations sur le fournisseur, telles que le nom et le GUID du fournisseur.

Cette macro doit être appelée dans un fichier .c ou .cpp pour définir le handle d’un fournisseur TraceLogging. Par exemple, si mon fournisseur est nommé MyCompany.MyComponent et que le GUID de contrôle est {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} , je le définirai en ajoutant le code suivant à l’un des fichiers .c ou .cpp dans mon composant :

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));

La macro ci-dessus TRACELOGGING_DEFINE_PROVIDER peut être considérée comme la définition d’une g_hMyProvider constante de handle de fournisseur, similaire au code suivant :

const TraceLoggingHProvider g_hMyProvider = ...;

Le handle résultant a une étendue de module et peut être utilisé n’importe où dans le module EXE, DLL ou SYS dans lequel il est défini. Utilisez la macro TRACELOGGING_DECLARE_PROVIDER si nécessaire (par exemple, dans un en-tête) pour transférer la déclaration du handle afin qu’elle puisse être utilisée par d’autres fichiers .c ou .cpp dans votre composant.

Lorsqu’un composant commence à s’exécuter, le fournisseur est dans un état non inscrit. Toute tentative de l’utiliser pour générer des événements sera ignorée en mode silencieux. Avant de pouvoir répondre à des appels en écriture, vous devez inscrire le fournisseur à l’aide de TraceLoggingRegister. Cette opération est généralement effectuée au démarrage du composant, par exemple dans main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)ou DriverEntry. À l’arrêt du composant, annulez l’inscription du fournisseur en appelant TraceLoggingUnregister.

Notes

Le handle de fournisseur défini par TRACELOGGING_DEFINE_PROVIDER est limité au module. Le handle peut être utilisé en fonction des besoins dans le fichier EXE, DLL ou SYS, mais il ne doit pas être utilisé en dehors de l’étendue du module, c’est-à-dire qu’il ne doit pas être passé à d’autres DLL dans le même processus. Chaque fichier EXE, DLL ou SYS doit utiliser son propre handle de fournisseur et doit effectuer ses propres inscriptions et désinscription. Dans les builds de débogage, une assertion se déclenche si vous tentez d’écrire à l’aide d’un handle de fournisseur à partir d’un autre module.

Nom et ID du fournisseur

ETW effectue le filtrage d’événements et le routage à l’aide de l’ID de fournisseur (également appelé GUID du fournisseur ou GUID de contrôle). Par exemple, si vous avez un fournisseur nommé MyCompany.MyComponent avec l’ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de fournisseur, vous pouvez démarrer une trace pour capturer des événements à partir de ce fournisseur à l’aide d’une commande tracelog telle que tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Tous les fournisseurs ETW sont identifiés par le nom et l’ID du fournisseur. Le nom et l’ID doivent être uniques afin de ne pas entrer en conflit avec d’autres fournisseurs. En outre, le nom et l’ID doivent être liés : une fois qu’un nom particulier est utilisé avec un ID particulier pour un fournisseur ETW, ce nom ne doit pas être utilisé avec un autre ID et cet ID ne doit pas être utilisé avec un autre nom.

L’ID de fournisseur peut être n’importe quel GUID unique, tel que généré à l’aide de l’outil guidgen sdk ou https://uuidgen.org. Toutefois, au lieu d’utiliser un GUID généré de manière aléatoire pour l’ID de fournisseur, Microsoft recommande de générer l’ID de fournisseur à partir du nom du fournisseur à l’aide de l’algorithme de hachage de nom ETW décrit ci-dessous. Cela offre plusieurs avantages : il est plus facile de mémoriser uniquement le nom ; l’ID et le nom sont automatiquement liés ; Les outils tels que tracelog, traceview, EventSource et WPR bénéficient d’une prise en charge spéciale pour les fournisseurs qui utilisent des ID générés à l’aide de cet algorithme.

Par exemple, si vous avez un fournisseur nommé MyCompany.MyComponent avec l’ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de fournisseur, vous pouvez démarrer une trace pour capturer des événements à partir de ce fournisseur à l’aide d’une commande tracelog telle que tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponent. Cela fonctionne, car l’ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de fournisseur a été généré en hachant le nom MyCompany.MyComponentdu fournisseur , de sorte que l’outil tracefmt considère comme -guid *MyCompany.MyComponent équivalent à -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Vous pouvez utiliser PowerShell pour obtenir l’ID de fournisseur d’un nom de fournisseur particulier à l’aide de l’algorithme de hachage de nom ETW via la classe EventSource :

[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid

Résultats :

Guid
----
ce5fa4ea-ab00-5402-8b76-9f76ac858fb5

En C#, l’algorithme de hachage de nom ETW peut être implémenté comme suit :

static Guid ProviderIdFromName(string name)
{
    var signature = new byte[] {
        0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8,
        0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB };
    var nameBytes = System.Text.Encoding.BigEndianUnicode.GetBytes(name.ToUpperInvariant());
    using (var sha1 = new System.Security.Cryptography.SHA1Managed())
    {
        sha1.TransformBlock(signature, 0, signature.Length, null, 0);
        sha1.TransformFinalBlock(nameBytes, 0, nameBytes.Length);
        var hash = sha1.Hash;
        Array.Resize(ref hash, 16);
        hash[7] = (byte)((hash[7] & 0x0F) | 0x50);
        return new Guid(hash);
    }
}

Exemples

#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;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	traceloggingprovider.h

Voir aussi

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite

Partager via