Écriture d’un manifeste d’instrumentation

Les applications et dll utilisent un manifeste d’instrumentation pour identifier leurs fournisseurs d’instrumentation et les événements que les fournisseurs écrivent. Un manifeste est un fichier XML qui contient les éléments qui identifient votre fournisseur. La convention consiste à utiliser .man comme extension pour votre manifeste. Le manifeste doit être conforme au manifeste d’événement XSD. Pour plus d’informations sur le schéma, consultez Schéma EventManifest.

Un fournisseur d’instrumentation est toute application ou DLL qui appelle les fonctions EventWriteEx, EventWriteString ou EventWriteTransfer pour écrire des événements dans une session de suivi d’événements (ETW) ou un canal de journal des événements. Une application peut définir un fournisseur d’instrumentation unique qui couvre tous les événements qu’elle écrit ou elle peut définir un fournisseur pour l’application et un fournisseur pour chacune de ses DLL. Le nombre de fournisseurs que l’application définit dans le manifeste dépend uniquement de la façon dont l’application souhaite organiser les événements qu’elle écrit.

L’avantage de spécifier un fournisseur pour chaque DLL est que vous pouvez ensuite activer et désactiver les fournisseurs individuels et donc les événements qu’ils génèrent. Cet avantage s’applique uniquement si le fournisseur est activé par une session de suivi ETW. Tous les événements qui spécifient un canal de journal des événements sont toujours écrits dans ce canal.

Le manifeste doit identifier le fournisseur et les événements qu’il écrit, mais les autres métadonnées telles que les canaux, les niveaux et les mots clés sont facultatives ; si vous définissez les métadonnées facultatives dépend de qui consommera les événements. Par exemple, si les administrateurs ou le personnel du support utilisent les événements à l’aide d’un outil comme le observateur d'événements Windows qui lit les événements à partir des canaux du journal des événements, vous devez définir les canaux sur lesquels les événements sont écrits. Toutefois, si le fournisseur est activé uniquement par une session de suivi ETW, vous n’avez pas besoin de définir de canaux.

Bien que les métadonnées des niveaux, des tâches, des opcodes et des mots clés soient facultatives, vous devez les utiliser pour regrouper ou compartimenter logiquement les événements. Le regroupement des événements permet aux consommateurs de consommer uniquement les événements qui sont intéressants. Par exemple, le consommateur peut interroger tous les événements pour lesquels le niveau est « critique » et mot clé est « écriture », ou pour tous les événements écrits par une tâche spécifique.

En plus des consommateurs qui utilisent le niveau et les mots clés pour consommer des types d’événements spécifiques, une session de suivi ETW peut utiliser les métadonnées de niveau et de mot clé pour indiquer à ETW de limiter les événements écrits dans le journal de suivi des événements. Par exemple, la session peut limiter les événements aux événements uniquement pour lesquels le niveau est « erreur » ou « critique » et où mot clé est « read ».

Un fournisseur peut définir des filtres qu’une session utilise pour filtrer les événements en fonction des données d’événement. Avec le niveau et les mots clés, ETW détermine si l’événement est écrit dans le journal, mais avec des filtres, le fournisseur utilise les critères de données de filtre pour déterminer s’il écrit l’événement dans cette session. Les filtres s’appliquent uniquement lorsqu’une session de suivi ETW active votre fournisseur.

Les sections suivantes montrent comment définir les composants du manifeste :

• Identification du fournisseur
• Définition des canaux vers lesquels les événements sont écrits
• Définition des niveaux de gravité des événements écrits par le fournisseur
• Définition des tâches et opérations effectuées par votre fournisseur
• Définition des mots clés qui classifient les événements écrits par le fournisseur
• Définition des filtres que le fournisseur utilise pour filtrer les événements qu’il écrit
• Définition des mappages nom/valeur référencés par vos données de modèle
• Définition des modèles qui définissent les données spécifiques à l’événement
• Définition des événements écrits par le fournisseur

Bien que vous puissiez créer manuellement un manifeste d’instrumentation, vous devez envisager d’utiliser l’outil ECManGen.exe inclus dans le dossier \Bin du KIT de développement logiciel (SDK) Windows. L’outil ECManGen.exe utilise une interface graphique graphique qui vous guide tout au long de la création d’un manifeste à partir de zéro sans jamais avoir à utiliser de balises XML. La connaissance des informations contenues dans cette section et dans la section Schéma EventManifest vous aidera lors de l’utilisation de l’outil.

Si vous utilisez Visual Studio comme éditeur XML, vous pouvez ajouter le schéma EventManifest au projet (voir le menu XML) pour tirer parti d’Intellisense, de la validation de schéma inline et d’autres fonctionnalités pour faciliter l’écriture du manifeste.

Après avoir écrit votre manifeste, utilisez le compilateur de messages pour valider le manifeste et générer les fichiers de ressources et d’en-tête que vous incluez dans votre fournisseur. Pour plus d’informations, consultez Compilation d’un manifeste d’instrumentation.

L’exemple suivant montre le squelette d’un manifeste d’événement entièrement défini.

<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    >

    <instrumentation>
        <events>
            <provider ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>