Partager via

Macro TraceLoggingChannel (traceloggingprovider.h)

  • Article

Macro wrapper TraceLogging qui définit le canal de l’événement.

La plupart des événements TraceLogging n’ont pas besoin de modifier le canal par défaut de l’événement et ne doivent pas utiliser TraceLoggingChannel.

Syntaxe

void TraceLoggingChannel(
  [in]  eventChannel
);

Paramètres

[in] eventChannel

Canal dans lequel l’événement doit être journalisé. Il s’agit d’une valeur entière comprise entre 0 et 255.

Consultez EVENT_DESCRIPTOR pour plus d’informations sur le canal d’événements.

Valeur de retour

None

Remarques

TraceLoggingChannel(eventChannel) peut être utilisé comme paramètre pour l’appel d’une macro TraceLoggingWrite . La plupart des événements TraceLogging n’ont pas besoin de modifier le canal par défaut de l’événement et ne doivent pas utiliser TraceLoggingChannel.

Le paramètre eventChannel doit être une constante au moment de la compilation de 0 à 255. Si aucun arg n’est TraceLoggingChannel(n) fourni, le canal par défaut est 11 (WINEVENT_CHANNEL_TRACELOGGING), ce qui indique qu’il s’agit d’un événement TraceLogging normal. Si plusieurs TraceLoggingChannel(n) arguments sont fournis, la valeur du dernier TraceLoggingChannel(n) paramètre est utilisée.

Les canaux sont utilisés dans les scénarios de suivi d’événements avancés pour Windows (ETW). Il s’agit notamment de l’écriture dans des consommateurs d’événements définis par le système, tels que le journal des événements Windows.

Avertissement

Si votre fournisseur s’exécute sur Windows avant Windows 10, n’utilisez pas TraceLoggingChannel. Pour qu’un événement soit reconnu comme compatible avec TraceLogging par les décodeurs d’événements, il doit avoir le canal défini sur la valeur par défaut (11) ou avoir été marqué comme événement TraceLogging par le runtime ETW pendant EventWrite. Ce marquage d’événement est activé en appelant EventSetInformation pour configurer le fournisseur en tant que fournisseur TraceLogging. EventSetInformation dans Windows 10 ou une version ultérieure active la prise en charge des événements TraceLogging quel que soit le canal, mais les versions antérieures de Windows nécessitent une mise à jour Windows avant de prendre en charge le marquage des événements TraceLogging. Pour les événements capturés sur des systèmes sans EventSetInformation mis à jour, le canal 11 est le seul moyen de reconnaître un événement TraceLogging, de sorte que les événements avec d’autres canaux peuvent ne pas décoder correctement.

TraceLogging et journal des événements

Dans la plupart des cas, les développeurs utilisent l’ETW basé sur un manifeste pour les événements qui doivent être enregistrés par le journal des événements. Le journal des événements est principalement destiné à collecter des événements de faible volume susceptibles d’être utiles à l’administrateur d’un système. L’ETW basé sur un manifeste fonctionne bien pour cela, car il prend en charge les événements organisés avec soin (tous les événements du composant sont décrits dans un seul fichier manifeste) et parce qu’il prend en charge les chaînes de message localisables qui peuvent aider l’administrateur à savoir comment réagir à l’événement.

Bien que les événements TraceLogging n’aient pas de chaînes de message et ne soient généralement pas organisés de manière centralisée, TraceLogging peut toujours être approprié pour certains scénarios de journal des événements. Par exemple, alors que les événements qui vont aux journaux Windows (application, sécurité, installation et système) doivent toujours avoir des chaînes de message localisées et doivent toujours être utiles à l’administrateur système, les événements enregistrés dans les journaux des applications et des services peuvent être plus techniques et enregistrer des informations de diagnostic. Lorsque vous écrivez dans les journaux des applications et des services, vous pouvez utiliser TraceLogging pour simplifier la gestion des événements journalisés.

L’utilisation d’événements TraceLogging avec le journal des événements Windows est similaire à l’utilisation d’événements basés sur un manifeste normal avec le journal des événements. Vous devez toujours créer et inscrire un manifeste pour définir le fournisseur et les canaux, mais vous n’avez pas besoin de définir les événements individuels dans le manifeste :

  • Écrivez un manifeste ETW qui définit votre fournisseur et les canaux du journal des événements. Le fournisseur dans le manifeste doit utiliser le même nom de fournisseur et le même GUID de fournisseur (ID de fournisseur) que vous avez utilisé dans votre macro TRACELOGGING_DEFINE_PROVIDER . Le manifeste n’a pas besoin d’inclure <event> ou <template> des définitions, car les événements TraceLogging sont auto-décrits.
  • Dans le processus de génération de votre composant, utilisez le compilateur de messages (MC.exe) à partir de SDK Windows 10.0.22621 ou version ultérieure pour compiler le manifeste. Cela génère les fichiers suivants :
    • ManifestName.h: en-tête C/C++ contenant des définitions constantes. Cela définit les constantes ChannelSymbol et ChannelSymbol_KEYWORD que vous devez utiliser dans vos événements TraceLogging. (Les noms réels des constantes seront différents pour chaque canal.)
    • ManifestName.rc: script du compilateur de ressources (RC.exe) qui ajoute les données BIN du manifeste à un fichier binaire (EXE, DLL ou SYS). Vous devez inclure ce script de ressource dans les ressources de l’un des fichiers binaires de votre composant.
    • ManifestNameTEMP.BIN, MSG00001.bin: manifeste des données BIN référencées par ManifestName.rc.
  • #include le fichier généré ManifestName.h dans le code qui doit générer des événements TraceLogging. Cela définit les constantes ChannelSymbol et ChannelSymbol_KEYWORD .
    • Si vous avez spécifié l’attribut symbol sur la <channel> définition ou <importChannel> dans le manifeste, le nom de ChannelSymbol correspond à la valeur de votre attribut de symbole . Sinon, ChannelSymbol sera ProviderSymbol_CHANNEL_ChannelName (c’est-à-dire qu’il utilisera le symbole de votre <provider> élément et le nom de votre <channel> élément ou <importChannel> ).
    • Le nom de ChannelSymbol_KEYWORD est le nom de ChannelSymbol suivi de _KEYWORD.
    • La constante ChannelSymbol_KEYWORD est générée uniquement par MC.exe 10.0.22621 ou version ultérieure.
  • Chaque événement TraceLogging qui doit accéder au journal des événements doit utiliserTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)pour définir le canal et mot clé pour l’événement. Par exemple, si le symbole de mon canal est MY_CHANNEL, j’ajouterai TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) en tant que paramètres à la TraceLoggingWrite macro pour l’événement.
  • Pour que le journal des événements reconnaisse votre fournisseur, les informations de votre manifeste doivent être incluses dans les ressources d’un module (FICHIER DLL, EXE ou SYS) qui sera installé sur le système cible.
  • Pour que le journal des événements reçoive des événements de votre fournisseur, vous devez inscrire votre manifeste sur le système cible à l’aide wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll de lors de l’installation du composant. Vous devez également annuler l’inscription de votre manifeste à l’aide wevtutil um ManifestFile.man de lors de la désinstallation du composant.

Important

Si votre fournisseur est inscrit auprès du journal des événements, tous les événements générés par votre fournisseur doivent avoir une mot clé non nulle spécifiée avec TraceLoggingKeyword, même si l’événement n’est pas destiné au journal des événements. Les événements avec mot clé 0 ne peuvent pas être filtrés efficacement et seront remis au journal des événements uniquement pour être ignorés. Si le journal des événements est à l’écoute des événements de votre fournisseur, tout événement avec le mot clé 0 augmente inutilement la surcharge du journal des événements.

Exemple d’événement TraceLogging pour le journal des événements :

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

Des mots clés spécifiés par l’utilisateur supplémentaires peuvent être ajoutés aux événements si nécessaire, soit en utilisant plusieurs arguments TraceLoggingKeyword , soit en spécifiant plusieurs mots clés dans un seul argument TraceLoggingKeyword , par exemple TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 10 (applications de bureau uniquement)
Serveur minimal pris en charge Windows Server 2012 R2
Plateforme cible Windows
En-tête traceloggingprovider.h

Voir aussi

EVENT_DESCRIPTOR

TraceLoggingWrite

Macros du wrapper TraceLogging