Partager via


Qualificateurs MOF de suivi d’événements

Utilisez les qualificateurs définis dans cette section lors de la création de votre classe MOF fournisseur, de la classe MOF d’événement, de la classe MOF de type d’événement et des propriétés de la classe MOF de type d’événement. Pour obtenir un exemple qui inclut certains de ces qualificateurs, consultez Publication de votre schéma d’événement.

Qualificateurs de classe MOF du fournisseur

Le tableau suivant répertorie les qualificateurs que vous pouvez spécifier sur une classe MOF de fournisseur.

Qualificateur Type de données Description
Guid Chaîne Obligatoire. Guid de chaîne qui identifie de manière unique un fournisseur. Par exemple, Guid(« {3F92E6E0-9886-434e-85DB-0D11D3904C0A} »). Il s’agit du même GUID que celui que vous utilisez lorsque vous appelez la fonction RegisterTraceGuids pour inscrire votre fournisseur.

 

Qualificateurs de classe MOF d’événement

Le tableau suivant répertorie les qualificateurs que vous pouvez spécifier sur une classe d’événements (la classe parente qui regroupe les classes de type d’événement associées).

Qualificateur Type de données Description
Guid Chaîne Obligatoire. Guid de chaîne qui identifie une classe d’événements. Par exemple, Guid(« {3F92E6E0-9886-434e-85DB-0D11D3904C0A} »). Les fournisseurs d’événements utilisent le GUID pour définir le EVENT_TRACE_HEADER. Membre GUID , afin que les consommateurs puissent déterminer la classe d’événements qu’ils reçoivent.
EventVersion Integer Ce qualificateur est facultatif pour la dernière version d’une classe de trace d’événements et est requis pour toutes les versions antérieures de la classe. La dernière version de la classe ne spécifie pas le qualificateur EventVersion ou a le numéro de version le plus élevé. Les numéros de version commencent par 0, par exemple EventVersion(0). En règle générale, lorsque vous créez une nouvelle version de la classe, vous renommez également la version <précédente en classname>_Vn, où n est un nombre incrémentiel commençant à 0. Pour obtenir un exemple, consultez FileIo et FileIo_V0.

 

Qualificateurs de classe MOF de type d’événement

Le tableau suivant répertorie les qualificateurs que vous pouvez spécifier sur une classe de type d’événement (la classe qui définit les données de propriété d’événement).

Qualificateur Valeur Description
EventType Integer Obligatoire. Identifie la classe de type d’événement. Par exemple, EventType(1). Le fournisseur d’événements utilise la même valeur de type d’événement pour définir EVENT_TRACE_HEADER. Class.Type. Si la même classe MOF est utilisée pour plusieurs types d’événements (car ils utilisent les mêmes données d’événement), spécifiez la valeur du type d’événement sous forme de tableau d’entiers, par exemple EventType{12,15}.
EventTypeName Chaîne Optionnel. Décrit le type d’événement. Par exemple, EventTypeName(« Start »). Si la même classe MOF est utilisée pour plusieurs types d’événements (car ils utilisent les mêmes données d’événement), spécifiez la valeur du nom du type d’événement sous forme de tableau de chaînes, par exemple EventTypeName{"Start », « End"}. Les éléments du tableau EventTypeName correspondent directement au tableau EventType.

 

Qualificateurs de propriété

Le tableau suivant répertorie les qualificateurs que vous pouvez spécifier sur une propriété.

Qualificateur Description
Bitmap Spécifie les positions de bits qui correspondent aux valeurs de chaîne. Si vous spécifiez ce qualificateur, vous devez également spécifier le qualificateur BitValues .
BitValues Valeurs de chaîne. Si le qualificateur BitMap est également spécifié, les chaînes correspondent directement aux valeurs du qualificateur BitMap . Dans le cas contraire, supposons que la valeur de propriété est un index de base unique dans les chaînes de valeur (le bit 1 correspond à la première chaîne de la liste).
Extension Fournit des informations supplémentaires sur la façon de consommer (interpréter) les données. La valeur d’extension ne respecte pas la casse. Incluez la valeur entre guillemets, par exemple, Extension(« Guid »). Les valeurs d’extension possibles sont les suivantes :
Guid
Indique que les données de propriété sont un GUID. Le type de données MOF doit être objet. La charge utile est censée être une structure GUID .
IPAddr et IPAddrV4
Les données sont une adresse IP V4. Le type de données MOF doit être objet. La charge utile est censée être un long non signé. Chaque octet du long non signé représente l’une des quatre parties de l’adresse IP (p1.p2.p3.p4). L’octet d’ordre inférieur contient la valeur de p1, l’octet suivant contient la valeur de p2, et ainsi de suite.
Avant Windows Vista : L’extension IPAddrV4 n’est pas prise en charge.
IPAddrV6
Les données sont une adresse IP V6. Le type de données MOF doit être objet. La charge utile est censée être une structure IN6_ADDR .
Avant Windows Vista : L’extension IPAddrV6 n’est pas prise en charge.
NoPrint
Indique que le consommateur ne doit pas imprimer ces données.
Port
Les données identifient un numéro de port. Le type de données MOF doit être objet. La charge utile est censée être un court non signé.
RString
Les caractères de nouvelle ligne ont été remplacés par des espaces. La charge utile est censée être une chaîne ANSI terminée par un caractère Null.
RWString
Les caractères de nouvelle ligne ont été remplacés par des espaces. La charge utile est censée être une chaîne de caractères larges terminée par null.
Sid
Les données représentent un SID d’objet blob binaire. Le type de données MOF doit être objet.
Le SID est d’une longueur variable. La valeur contenue dans les 4 premiers octets (ULONG) indique si l’objet blob contient un SID. Si les 4 premiers octets (ULONG) de l’objet blob sont non nuls, l’objet blob contient un SID. La première partie de l’objet blob contient le TOKEN_USER (la structure est alignée sur une limite de 8 octets) et la deuxième partie contient le SID. Pour traiter la partie SID de l’objet blob :
  • Définir un pointeur d’octets vers le début de l’objet blob
  • Multipliez la taille du pointeur pour le journal des événements par 2 et ajoutez le produit au pointeur d’octets (le membre PointerSize de TRACE_LOGFILE_HEADER contient la valeur de taille du pointeur)

Vous pouvez utiliser la macro suivante pour déterminer la longueur du SID.
#define SeLengthSid( Sid ) \
  (8 + (4 * ((SID *)Sid)->SubAuthorityCount))
SizeT
Indique que la propriété contient une valeur de pointeur. La taille de la valeur du pointeur dépend du système d’exploitation utilisé pour journaliser l’événement ; la charge utile contient une valeur de 4 octets pour les systèmes 32 bits ou une valeur de 8 octets pour les systèmes 64 bits. Le type de données MOF doit être objet.
Les consommateurs doivent ignorer le type de données et le qualificateur format si la propriété inclut l’extension SizeT . Pour déterminer la taille des données à lire pour la propriété, utilisez :
Avant Windows Vista : La valeur PointerSize peut ne pas être exacte. Par exemple, sur un ordinateur 64 bits, une application 32 bits enregistre des pointeurs de 4 octets ; Toutefois, la session définit PointerSize sur 8.
Variante
Les données représentent un objet blob. Les quatre premiers octets (uint32) indiquent la taille de l’objet blob. Le type de données MOF doit être objet.
Wmitime
Convertit l’horodatage en heure système. Le type de données MOF doit être objet. La charge utile est censée être un entier 64 bits non signé.
Avant Windows Vista : Non disponible.
Format Définit le format des données de propriété. Par exemple, l’inclusion de Format(« w ») sur une propriété de chaîne indique que la chaîne est une chaîne large. Les valeurs possibles sont les suivantes :
Terme Description
C
Affiche la valeur de la propriété sous la forme d’un caractère ASCII. Vous pouvez utiliser ce qualificateur avec les types de données uint8 .
s
Traitez le tableau de caractères comme une chaîne terminée par une valeur Null. La chaîne est une chaîne à caractères larges si le type de données est char16 ; sinon, la chaîne est une chaîne de caractères ASCII.
W
La valeur de la propriété est une chaîne de caractères larges. Vous pouvez utiliser ce qualificateur avec des types de données de chaîne .
x
Afficher la valeur de la propriété sous la forme d’un nombre hexadécimal. Vous pouvez utiliser ce qualificateur avec des types de données entiers 16, 32 et 64 bits.

 

Pointeur

Indique que la propriété contient une valeur de pointeur. La taille de la valeur du pointeur dépend du système d’exploitation utilisé pour journaliser l’événement ; la charge utile contient une valeur de 4 octets pour les systèmes 32 bits ou une valeur de 8 octets pour les systèmes 64 bits. Le type de données MOF doit être objet.

Les consommateurs doivent ignorer le type de données et le qualificateur format si la propriété inclut l’extension SizeT . Pour déterminer la taille des données à lire pour la propriété, utilisez :

Avant Windows Vista : La valeur PointerSize peut ne pas être exacte. Par exemple, sur un ordinateur 64 bits, une application 32 bits enregistre des pointeurs de 4 octets ; Toutefois, la session définit PointerSize sur 8.

Notez que certains événements utilisent PointerType au lieu de Pointer ; n’utilisez pas PointerType.

StringTermination Indique comment la propriété de chaîne est terminée. Par exemple, StringTermination(« NullTerminated ») indique que la propriété de chaîne est terminée par null. Les valeurs possibles sont les suivantes :
Compté

La longueur de la chaîne est incorporée au début de la chaîne en tant que valeur USHORT .

NotCounted

La chaîne n’est pas terminée par null et la longueur de la chaîne n’est pas incorporée au début de la chaîne. Dans ce cas, la chaîne doit être le dernier élément et occuper tout l’espace jusqu’à la fin des données d’événement.

NullTerminated

La chaîne est terminée par null. Si vous ne spécifiez pas le qualificateur StringTermination , la chaîne est supposée être terminée par null.

ReverseCounted

La longueur de la chaîne est incorporée au début de la chaîne en tant que valeur USHORT au format big-endian.

ValueDescriptions Fournit des descriptions pour chaque valeur dans le qualificateur Valeurs . Les fonctions TdhEnumerateProviderFieldInformation et TdhQueryProviderFieldInformation retournent ces descriptions lorsque vous essayez de récupérer des informations de mot clé et de niveau. Les descriptions sont facultatives. Si vous ne fournissez pas les descriptions, les fonctions retournent NULL. Pour plus d’informations, consultez Spécification du niveau et de l’activation des valeurs d’indicateurs pour un fournisseur .
ValueMap Spécifie les valeurs d’index entiers ou d’indicateur qui sont mappées à des valeurs de chaîne. Si vous spécifiez ce qualificateur, vous devez également spécifier le qualificateur Values et éventuellement le qualificateur ValueType . Notez qu’ETW ne prend pas en charge l’option WMI qui consiste à avoir des chaînes pour les valeurs de mappage de valeurs.

L’exemple suivant montre comment utiliser les qualificateurs ValueMap, Values et ValueType.

ValueType("flag"),
ValueMap {"0x01", "0x02", "0x04", "0x08"},
Values {"ValueMapFlag1", "ValueMapFlag2", "ValueMapFlag4", "ValueMapFlag8"}]
Valeurs Valeurs de chaîne. Si le qualificateur ValueMap est également spécifié, les chaînes correspondent directement aux valeurs du qualificateur ValueMap . Sinon, supposons que la valeur de la propriété est un index de base zéro dans les chaînes de valeur.
ValueType Indique si les valeurs ValueMap sont des valeurs d’index entiers ou des valeurs d’indicateur de bits. Si vous ne spécifiez pas ce qualificateur, les valeurs d’index entiers sont supposées. Pour spécifier que les valeurs sont des valeurs d’index entiers, utilisez ValueType(« index »). Pour spécifier que les valeurs sont des valeurs d’indicateur de bits, utilisez ValueType(« flag »).
WmiDataId Chaque propriété doit contenir le qualificateur WmiDataId . WmiDataId définit l’ordre dans lequel le consommateur lit les données d’événement. La valeur de WmiDataId commence à 1 et s’incrémente pour chaque propriété de la classe . Par exemple, WmiDataId(1).
XMLFragment Indique que les données sont au format XML et prêtes à être affichées sans autre mise en forme.

 

Spécification des valeurs de niveau et d’activation des indicateurs pour un fournisseur

Pour documenter le niveau et activer les indicateurs qu’un contrôleur utiliserait pour activer votre fournisseur, incluez les propriétés « Level » et « Flags » dans votre classe MOF du fournisseur. Les noms des propriétés Level et Flags respectent la casse. Les propriétés doivent inclure les qualificateurs Values et ValueMap , qui spécifient le niveau possible et activent les valeurs d’indicateur. Le ValueMap pour les valeurs d’indicateur d’activation doit être des valeurs de bits (indicateur). Le qualificateur ValueDescriptions est facultatif, mais vous devez l’utiliser pour fournir des descriptions pour chaque valeur possible. Les descriptions sont utilisées lorsqu’une personne appelle les fonctions TdhEnumerateProviderFieldInformation et TdhQueryProviderFieldInformation pour obtenir le niveau possible et activer les valeurs d’indicateurs (mots clés) pour le fournisseur.

L’exemple suivant montre une classe de fournisseur qui spécifie le niveau possible et active les valeurs d’indicateurs.

[Dynamic,
 Description("IIS_Trace") : amended,
 guid("{3a2a4e84-4c21-4981-ae10-3fda0d9b0f83}"),
 locale("MS\\0x409")]
class IIS_Trace : EventTrace
{
    [Description ("Enable Flags") : amended,
        ValueDescriptions{
             "Allow_tracing_only_selected_requests ",
             "IIS_authentication_events ",
             "IIS_security_events ",
             "IIS_filter_events ",
             "IIS_static_file_events ",
             "IIS_CGI_events ",
             "IIS_compression_events ",
             "IIS_cache_events ",
             "IIS_request_notifications_events ",
             "IIS_module_events ",
             "IIS_FastCGI_events "},
        DefineValues{
             "UseUrlFilter",
             "IISAuthentication",
             "IISSecurity",
             "IISFilter",
             "IISStaticFile",
             "IISCGI",
             "IISCompression",
             "IISCache",
             "IISRequestNotification",
             "IISModule",
             "IISFastCGI"},
        Values{
             "UseUrlFilter",
             "IISAuthentication",
             "IISSecurity",
             "IISFilter",
             "IISStaticFile",
             "IISCGI",
             "IISCompression",
             "IISCache",
             "IISRequestNotification",
             "IISModule",
             "IISFastCGI"},
        ValueMap{
             "0x00000001",
             "0x00000002",
             "0x00000004",
             "0x00000008",
             "0x00000010",
             "0x00000020",
             "0x00000040",
             "0x00000080",
             "0x00000100",
             "0x00000200",
             "0x00001000"}: amended
    ]
    uint32 Flags;

    [Description ("Levels") : amended,
        ValueDescriptions{
            "Abnormal exit or termination",
            "Severe errors that need logging",
            "Warnings such as allocation failure",
            "Includes non-error cases",
            "Detailed traces from intermediate steps" } : amended,
         DefineValues{
            "TRACE_LEVEL_FATAL",
            "TRACE_LEVEL_ERROR",
            "TRACE_LEVEL_WARNING"
            "TRACE_LEVEL_INFORMATION",
            "TRACE_LEVEL_VERBOSE" },
        Values{
            "Fatal",
            "Error",
            "Warning",
            "Information",
            "Verbose" },
        ValueMap{
            "0x1",
            "0x2",
            "0x3",
            "0x4",
            "0x5" },
        ValueType("index")
    ]
    uint32 Level;
};