Définition de mots clés utilisés pour classifier les types d’événements

Un mot clé ETW est un masque de bits 64 bits utilisé pour indiquer l’appartenance d’un événement à un ensemble de catégories d’événements. Chaque bit dans le mot clé correspond à une catégorie. Si le mot clé d’un événement a un bit défini, l’événement appartient à la catégorie d’événements correspondant à ce bit.

Les 48 bits faibles du mot clé (masque de bits 0x0000FFFFFFFFFFFF) sont définis par le fournisseur d’événements (l’auteur du manifeste). Les 16 premiers bits du mot clé (masque de bits 0xFFFF000000000000) sont définis par Microsoft. Consultez winmeta.h ou winmeta.xml dans le dossier Kits Windows include pour obtenir les définitions des mots clés définis par Microsoft.

Les fournisseurs utilisent des mots clés pour classer différents types d’événements. Par exemple, vous pouvez définir mot clé bit 0 (mot clé valeur 0x1) comme catégorie de lecture, puis appliquer la mot clé de lecture à tout événement qui effectue une opération de lecture telle que la lecture à partir d’un fichier ou d’un registre. Les consommateurs peuvent ensuite utiliser les valeurs de bits mot clé pour filtrer différentes classifications d’événements. Par exemple, le consommateur peut définir la propriété MatchAnyKeyword de la session de collection d’événements sur 0x1 pour que la session collecte uniquement les événements de la catégorie de lecture .

Une session de collection d’événements ETW peut utiliser les mots clés (de la même façon qu’elle utilise level) pour limiter les événements que le service ETW écrit dans son fichier journal de suivi des événements. Une session de suivi peut activer le fournisseur à l’aide de deux ensembles de masques de bits mot clé : un masque de bits « MatchAnyKeyword » où l’événement est écrit si l’un des bits mot clé de l’événement correspond à l’un des bits définis dans ce masque, et un masque de bits « MatchAllKeyword » où, pour les événements correspondant au cas « MatchAnyKeyword », l’événement est écrit uniquement si tous les bits du masque « MatchAllKeyword » existent dans le mot clé Masque.

Par exemple, si le fournisseur définit un événement qui spécifie un mot clé de lecture (bit 0 = 0x1) et un mot clé d’accès local (bit 1 = 0x2), et un deuxième événement qui spécifie un mot clé de lecture (bit 0 = 0x1) et un mot clé d’accès à distance (bit 2 = 0x4), vous pouvez définir le masque de bits « MatchAnyKeyword » de la session d’événements sur 0x1 (read) et le masque de bits « MatchAllKeyword » sur (read) et le masque de bits « MatchAllKeyword » sur 0x0 (none) pour recevoir tous les événements de lecture, ou vous pouvez définir le masque de bits 0x1 « MatchAnyKeyword » sur et le masque de bits « MatchAllKeyword » sur 0x3 (lecture + local) pour recevoir uniquement les lectures locales.

Pour définir un mot clé pour votre fournisseur, utilisez l’élément mot clé. Une fois qu’une mot clé a été définie pour le fournisseur, vous pouvez affecter le mot clé à n’importe quel événement du fournisseur à l’aide de l’attribut keywords de l’élément d’événement.

Vous devez spécifier le nom et les attributs de masque du mot clé. Le masque doit être un entier avec un bit défini, entre le bit 0 et le bit 47, par mask="256"mask="0x100" exemple ou pour définir mot clé bit 8. Les bits 48 à 63 sont définis par Microsoft (voir winmeta.h ou winmeta.xml) et ne peuvent pas être utilisés dans l’élément mot clé.

Les attributs de symbole et de message sont facultatifs.

L’exemple suivant montre comment définir un mot clé.

<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 name="Microsoft-Windows-SampleProvider"
                guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
                symbol="PROVIDER_GUID"
                resourceFileName="<path to the exe or dll that contains the metadata resources>"
                messageFileName="<path to the exe or dll that contains the string resources>"
                message="$(string.Provider.Name)">

                . . .

                <keywords>
                    <keyword name="Read" mask="0x1" symbol="READ_KEYWORD"/>
                    <keyword name="Write" mask="0x2" symbol="WRITE_KEYWORD"/>
                    <keyword name="Local" mask="0x4" symbol="LOCAL_KEYWORD"/>
                    <keyword name="Remote" mask="0x8" symbol="REMOTE_KEYWORD"/>
                </keywords>

                . . .

            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Sample Provider"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>