Définition de modèles de données d’événement

Les fournisseurs utilisent des modèles de données pour définir les données spécifiques à un événement qu’ils incluent avec un événement et pour définir les données de filtre qu’une session de suivi ETW peut transmettre au fournisseur lorsqu’elle active le fournisseur. Si l’événement n’inclut pas de données spécifiques à l’événement, vous ne définirez pas de modèle. Pour définir un modèle, utilisez l’élément template . Un modèle inclut un élément de données pour chaque élément de données que le fournisseur inclut avec l’événement. Vous pouvez spécifier des types intégraux, des chaînes, des tableaux et des structures. Vous devez écrire les données d’événement dans l’ordre dans lequel les éléments de données ont été définis dans le modèle.

Vous pouvez également inclure dans le modèle, un fragment XML que les consommateurs doivent utiliser pour déterminer comment restituer les données d’événement. Si vous n’incluez pas le fragment, les consommateurs doivent afficher les données d’événement dans l’ordre dans lequel les éléments de données ont été définis dans le modèle.

Lorsque vous définissez un modèle, vous devez lui donner un identificateur de modèle que vous utilisez pour référencer le modèle dans une définition d’événement. Chaque élément de données du modèle doit spécifier un nom et un type de données d’entrée (pour obtenir la liste des types d’entrée, consultez la section Remarques du type complexe InputType ). Si le type de données d’entrée peut être rendu dans plusieurs formats, vous devez spécifier le type de données de sortie qui indique aux consommateurs comment restituer l’élément de données. Par exemple, un type de données d’entrée UInt32 peut être rendu sous forme d’entier non signé, d’identificateur de thread, d’adresse IPv4 et de code d’erreur Win32, entre autres. Si vous ne spécifiez pas le type de données de sortie, les consommateurs doivent utiliser le type de sortie par défaut du type d’entrée pour restituer l’élément de données.

Pour spécifier un tableau, incluez l’attribut count sur l’élément de données et définissez-le sur le nombre d’éléments dans le tableau. Le tableau peut être un tableau de taille variable ou un tableau de taille fixe. Si le tableau est un tableau de taille fixe, définissez count sur la taille du tableau. Par exemple, si un tableau d’entiers a une taille fixe de 10, définissez nombre sur 10. Lorsque vous écrivez le tableau, vous devez écrire 40 octets de données.

Si le tableau est un tableau de taille variable, définissez count sur le nom de l’élément de données qui contient la taille du tableau. Si le tableau contient des pointeurs, l’adresse des pointeurs est écrite en tant que données d’événement, et non en tant que données vers lesquelles pointent les pointeurs.

Vous devez spécifier l’attribut length si l’élément de données est un objet blob binaire. Vous pouvez également spécifier l’attribut length pour les chaînes de longueur fixe.

Spécifiez l’attribut map si l’élément de données représente une valeur d’énumération et que vous souhaitez que le consommateur imprime une chaîne pour la valeur au lieu de la valeur elle-même.

Si vous incluez des structures dans le modèle, vous devez écrire les membres de la structure individuellement au lieu d’écrire la structure, sauf si vous pouvez garantir l’alignement des limites sur 8 octets.

Vous devez examiner attentivement les informations que vous incluez dans les événements, en particulier lorsque les événements sont écrits dans les canaux globaux. En règle générale, vous ne devez pas inclure d’informations privées dans les événements. Cela inclut les mots de passe en texte clair et les informations utilisateur personnelles. En outre, les programmes exécutés par l’utilisateur, les URL que l’utilisateur a visitées et d’autres informations relatives aux activités de l’utilisateur sur l’ordinateur doivent être considérés comme privés.

Si vous devez enregistrer des URL et des noms d’utilisateur dans les événements, ne les écrivez pas dans les canaux Windows (Système et Application), car ces canaux sont lisibles par tous les utilisateurs authentifiés. Au lieu de cela, écrivez-les dans vos propres canaux opérationnels ou analytiques. Définissez les autorisations d’accès sur ces canaux pour autoriser uniquement les administrateurs à lire les événements. Vous devrez peut-être fournir une divulgation appropriée pour informer les utilisateurs du fait que des informations privées sont mises à la disposition des administrateurs.

L’exemple suivant montre comment définir un modèle. Vous devez spécifier l’attribut tid du modèle que vous référencez dans la définition d’événement ou la définition de filtre.

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

                . . .

                <maps>
                    <valueMap name="TransferType">
                        <map value="1" message="$(string.TransferType.Download)"/>
                        <map value="2" message="$(string.TransferType.Upload)"/>
                        <map value="3" message="$(string.TransferType.UploadReply)"/>
                    </valueMap>
                    <bitMap name="DaysOfTheWeek">
                        <map value="0x1" message="$(string.DaysOfTheWeek.Sunday)"/>
                        <map value="0x2" message="$(string.DaysOfTheWeek.Monday)"/>
                        <map value="0x4" message="$(string.DaysOfTheWeek.Tuesday)"/>
                        <map value="0x8" message="$(string.DaysOfTheWeek.Wednesday)"/>
                        <map value="0x10" message="$(string.DaysOfTheWeek.Thursday)"/>
                        <map value="0x20" message="$(string.DaysOfTheWeek.Friday)"/>
                        <map value="0x40" message="$(string.DaysOfTheWeek.Saturday)"/>
                    </bitMap>
                </maps>

                <templates>
                    <template tid="t2">
                        <data name="TransferName" inType="win:UnicodeString"/>
                        <data name="Day" inType="win:UInt32" map="DaysOfTheWeek"/>
                        <data name="Transfer" inType="win:UInt32" map="TransferType"/>
                    </template>

                    <template tid="t3">
                        <data name="TransferName" inType="win:UnicodeString"/>
                        <data name="ErrorCode" inType="win:Int32" outType="win:HResult"/>
                        <data name="FilesCount" inType="win:UInt16" />
                        <data name="Files" inType="win:UnicodeString" count="FilesCount"/>
                        <data name="BufferSize" inType="win:UInt32" />
                        <data name="Buffer" inType="win:Binary" length="BufferSize"/>
                        <data name="Certificate" inType="win:Binary" length="11" />
                        <data name="IsLocal" inType="win:Boolean" />
                        <data name="Path" inType="win:UnicodeString" />
                        <data name="ValuesCount" inType="win:UInt16" />
                        <struct name="Values" count="ValuesCount" >
                            <data name="Value" inType="win:UInt16" />
                            <data name="Name" inType="win:UnicodeString" />
                        </struct>
                    </template>
                </templates>

                . . .

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

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Sample Provider"/>
                <string id="TransferType.Download" value="Download"/>
                <string id="TransferType.Upload" value="Upload"/>
                <string id="TransferType.UploadReply" value="Upload-reply"/>
                <string id="DaysOfTheWeek.Sunday" value="Sunday"/>
                <string id="DaysOfTheWeek.Monday" value="Monday"/>
                <string id="DaysOfTheWeek.Tuesday" value="Tuesday"/>
                <string id="DaysOfTheWeek.Wednesday" value="Wednesday"/>
                <string id="DaysOfTheWeek.Thursday" value="Thursday"/>
                <string id="DaysOfTheWeek.Friday" value="Friday"/>
                <string id="DaysOfTheWeek.Saturday" value="Saturday"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>