Qualificadores de MOF de rastreamento de eventos

Use os qualificadores definidos nesta seção ao criar a classe MOF do provedor, a classe MOF do evento, a classe MOF do tipo de evento e as propriedades da classe MOF do tipo de evento. Para obter um exemplo que inclua alguns desses qualificadores, consulte Publicar seu esquema de evento.

Qualificadores de classe MOF do provedor

A tabela a seguir lista os qualificadores que você pode especificar em uma classe MOF do provedor.

Qualificador Tipo de dados Descrição
Guid Cadeia de caracteres Obrigatórios. Guid de cadeia de caracteres que identifica exclusivamente um provedor. Por exemplo, Guid("{3F92E6E0-9886-434e-85DB-0D11D3904C0A}"). Esse é o mesmo GUID que você usa quando chama a função RegisterTraceGuids para registrar seu provedor.

 

Qualificadores de classe MOF de evento

A tabela a seguir lista os qualificadores que você pode especificar em uma classe de evento (a classe pai que agrupa classes de tipo de evento relacionadas).

Qualificador Tipo de dados Descrição
Guid Cadeia de caracteres Obrigatórios. Guid de cadeia de caracteres que identifica uma classe de eventos. Por exemplo, Guid("{3F92E6E0-9886-434e-85DB-0D11D3904C0A}"). Os provedores de eventos usam o Guid para definir o EVENT_TRACE_HEADER. Membro Guid , para que os consumidores possam determinar a classe de eventos que estão recebendo.
EventVersion Inteiro Esse qualificador é opcional para a versão mais recente de uma classe de rastreamento de evento e é necessário para todas as versões mais antigas da classe. A versão mais recente da classe não especifica o qualificador EventVersion ou tem o número de versão mais alto. Os números de versão começam com 0, por exemplo, EventVersion(0). Normalmente, ao criar uma nova versão da classe, você também renomeia a versão anterior para <classname>_Vn, em que n é um número incremental a partir de 0. Para obter um exemplo, consulte FileIo e FileIo_V0.

 

Qualificadores de classe MOF do tipo de evento

A tabela a seguir lista os qualificadores que você pode especificar em uma classe de tipo de evento (a classe que define os dados da propriedade do evento).

Qualificador Valor Descrição
EventType Inteiro Obrigatórios. Identifica a classe de tipo de evento. Por exemplo, EventType(1). O provedor de eventos usa o mesmo valor de tipo de evento para definir EVENT_TRACE_HEADER. Class.Type. Se a mesma classe MOF for usada para vários tipos de evento (porque eles usam os mesmos dados de evento), especifique o valor do tipo de evento como uma matriz de inteiros, por exemplo, EventType{12,15}.
EventTypeName Cadeia de caracteres Opcional. Descreve o tipo de evento. Por exemplo, EventTypeName("Start"). Se a mesma classe MOF for usada para vários tipos de evento (porque eles usam os mesmos dados de evento), especifique o valor do nome do tipo de evento como uma matriz de cadeias de caracteres, por exemplo, EventTypeName{"Start", "End"}. Os elementos da matriz EventTypeName correspondem diretamente à matriz EventType.

 

Qualificadores de propriedade

A tabela a seguir lista os qualificadores que você pode especificar em uma propriedade.

Qualificador Descrição
Bitmap Especifica as posições de bit que são mapeadas para valores de cadeia de caracteres. Se você especificar esse qualificador, também deverá especificar o qualificador BitValues .
BitValues Valores de cadeia de caracteres. Se o qualificador bitMap também for especificado, as cadeias de caracteres corresponderão diretamente aos valores no qualificador BitMap . Caso contrário, suponha que o valor da propriedade seja um índice baseado nas cadeias de caracteres de valor (bit um corresponde à primeira cadeia de caracteres da lista).
Extensão Fornece informações adicionais sobre como consumir (interpretar) os dados. O valor da extensão não diferencia maiúsculas de minúsculas. Inclua o valor entre aspas, por exemplo, Extension("Guid"). Os valores de extensão possíveis são:
Guid
Indica que os dados da propriedade são um Guid. O tipo de dados MOF deve ser objeto. Espera-se que o conteúdo seja uma estrutura GUID .
IPAddr e IPAddrV4
Os dados são um endereço IP V4. O tipo de dados MOF deve ser objeto. Espera-se que o conteúdo seja um longo sem sinal. Cada byte do long sem sinal representa uma das quatro partes do endereço IP (p1.p2.p3.p4). O byte de baixa ordem contém o valor para p1, o próximo byte contém o valor para p2 e assim por diante.
Antes de Windows Vista: não há suporte para a extensão IPAddrV4.
IPAddrV6
Os dados são um endereço IP V6. O tipo de dados MOF deve ser objeto. Espera-se que o conteúdo seja uma estrutura IN6_ADDR .
Antes de Windows Vista: não há suporte para a extensão IPAddrV6.
NoPrint
Indica que o consumidor não deve imprimir esses dados.
Porta
Os dados identificam um número de porta. O tipo de dados MOF deve ser objeto. Espera-se que o conteúdo seja um curto sem sinal.
RString
Os caracteres newline foram substituídos por espaços. Espera-se que o conteúdo seja uma cadeia de caracteres ANSI terminada em nulo.
RWString
Os caracteres newline foram substituídos por espaços. Espera-se que o conteúdo seja uma cadeia de caracteres de caracteres largos com término nulo.
Sid
Os dados representam um SID de blob binário. O tipo de dados MOF deve ser objeto.
O SID tem um comprimento variável. O valor contido nos primeiros 4 bytes (ULONG) indica se o blob contém um SID. Se o primeiro ULONG (4 bytes) do blob não for zero, o blob conterá um SID. A primeira parte do blob contém o TOKEN_USER (a estrutura está alinhada em um limite de 8 bytes) e a segunda parte contém o SID. Para abordar a parte SID do blob:
  • Definir um ponteiro de bytes para o início do blob
  • Multiplique o tamanho do ponteiro para o log de eventos por 2 e adicione o produto ao ponteiro de bytes (o membro PointerSize do TRACE_LOGFILE_HEADER contém o valor do tamanho do ponteiro)

Você pode usar a macro a seguir para determinar o comprimento do SID.
#define SeLengthSid( Sid ) \
  (8 + (4 * ((SID *)Sid)->SubAuthorityCount))
SizeT
Indica que a propriedade contém um valor de ponteiro. O tamanho do valor do ponteiro depende do sistema operacional usado para registrar o evento em log; o conteúdo conterá um valor de 4 bytes para sistemas de 32 bits ou um valor de 8 bytes para sistemas de 64 bits. O tipo de dados MOF deve ser objeto.
Os consumidores devem ignorar o tipo de dados e o qualificador de formato se a propriedade incluir a extensão SizeT . Para determinar o tamanho dos dados a serem lidos para a propriedade, use:
Antes de Windows Vista: o valor pointerSize pode não ser preciso. Por exemplo, em um computador de 64 bits, um aplicativo de 32 bits registrará ponteiros de 4 bytes; no entanto, a sessão definirá PointerSize como 8.
Variante
Os dados representam um blob. Os quatro primeiros bytes (uint32) indicam o tamanho do blob. O tipo de dados MOF deve ser objeto.
WmiTime
Converte o carimbo de data/hora para a hora do sistema. O tipo de dados MOF deve ser objeto. Espera-se que o conteúdo seja um inteiro sem sinal de 64 bits.
Antes de Windows Vista: Não disponível.
Formato Define o formato dos dados da propriedade. Por exemplo, incluir Format("w") em uma propriedade de cadeia de caracteres indica que a cadeia de caracteres é uma cadeia de caracteres larga. Os valores possíveis são:
Termo Descrição
C
Exiba o valor da propriedade como um caractere ASCII. Você pode usar esse qualificador com tipos de dados uint8 .
s
Trate a matriz de caracteres como uma cadeia de caracteres terminada em nulo. A cadeia de caracteres será uma cadeia de caracteres larga se o tipo de dados for char16; caso contrário, a cadeia de caracteres é uma cadeia de caracteres ASCII.
W
O valor da propriedade é uma cadeia de caracteres larga. Você pode usar esse qualificador com tipos de dados de cadeia de caracteres.
X
Exiba o valor da propriedade como um número hexadecimal. Você pode usar esse qualificador com tipos de dados inteiros de 16, 32 e 64 bits.

 

Ponteiro

Indica que a propriedade contém um valor de ponteiro. O tamanho do valor do ponteiro depende do sistema operacional usado para registrar o evento em log; o conteúdo conterá um valor de 4 bytes para sistemas de 32 bits ou um valor de 8 bytes para sistemas de 64 bits. O tipo de dados MOF deve ser objeto.

Os consumidores devem ignorar o tipo de dados e o qualificador de formato se a propriedade incluir a extensão SizeT . Para determinar o tamanho dos dados a serem lidos para a propriedade, use:

Antes de Windows Vista: o valor pointerSize pode não ser preciso. Por exemplo, em um computador de 64 bits, um aplicativo de 32 bits registrará ponteiros de 4 bytes; no entanto, a sessão definirá PointerSize como 8.

Observe que alguns eventos usam PointerType em vez de Pointer; não use PointerType.

StringTermination Indica como a propriedade de cadeia de caracteres é encerrada. Por exemplo, StringTermination("NullTerminated") indica que a propriedade de cadeia de caracteres é encerrada em nulo. Os valores possíveis são:
Contado

O comprimento da cadeia de caracteres é inserido no início da cadeia de caracteres como um valor USHORT .

NotCounted

A cadeia de caracteres não é encerrada em nulo e o comprimento da cadeia de caracteres não é inserido no início da cadeia de caracteres. Nesse caso, a cadeia de caracteres deve ser o último elemento e ocupar todo o espaço até o final dos dados do evento.

NullTerminated

A cadeia de caracteres é encerrada em nulo. Se você não especificar o qualificador StringTermination , a cadeia de caracteres será considerada nula.

ReverseCounted

O comprimento da cadeia de caracteres é inserido no início da cadeia de caracteres como um valor USHORT no formato big-endian.

ValueDescriptions Fornece descrições para cada valor no qualificador valores . As funções TdhEnumerateProviderFieldInformation e TdhQueryProviderFieldInformation retornam essas descrições quando você tenta recuperar informações de nível e palavra-chave. As descrições são opcionais. Se você não fornecer as descrições, as funções retornarão NULL. Consulte Especificando o nível e habilite valores de sinalizadores para um provedor para obter mais detalhes.
Valuemap Especifica os valores de índice inteiro ou sinalizador que são mapeados para valores de cadeia de caracteres. Se você especificar esse qualificador, também deverá especificar o qualificador de Valores e, opcionalmente, o qualificador ValueType . Observe que o ETW não dá suporte à opção WMI de ter cadeias de caracteres para valores de mapa de valor.

O exemplo a seguir mostra como usar os qualificadores ValueMap, Values e ValueType.

ValueType("flag"),
ValueMap {"0x01", "0x02", "0x04", "0x08"},
Values {"ValueMapFlag1", "ValueMapFlag2", "ValueMapFlag4", "ValueMapFlag8"}]
Valores Valores de cadeia de caracteres. Se o qualificador ValueMap também for especificado, as cadeias de caracteres corresponderão diretamente aos valores no qualificador ValueMap . Caso contrário, suponha que o valor da propriedade seja um índice baseado em zero nas cadeias de caracteres de valor.
ValueType Indica se os valores valueMap são valores de índice inteiros ou valores de sinalizador de bit. Se você não especificar esse qualificador, os valores de índice inteiro serão assumidos. Para especificar que os valores são valores de índice inteiros, use ValueType("index"). Para especificar que os valores são valores de sinalizador de bit, use ValueType("flag").
WmiDataId Cada propriedade deve conter o qualificador WmiDataId . WmiDataId define a ordem na qual o consumidor lê os dados do evento. O valor de WmiDataId começa em 1 e incrementa para cada propriedade na classe. Por exemplo, WmiDataId(1).
XMLFragment Indica que os dados estão no formato XML e prontos para serem exibidos sem formatação adicional.

 

Especificando o nível e habilitando valores de sinalizadores para um provedor

Para documentar o nível e habilitar os sinalizadores que um controlador usaria para habilitar seu provedor, inclua as propriedades "Nível" e "Sinalizadores" na classe MOF do provedor. Os nomes das propriedades Level e Flags diferenciam maiúsculas de minúsculas. As propriedades devem incluir os qualificadores Values e ValueMap , que especificam o nível possível e habilitam valores de sinalizador. O ValueMap para os valores de sinalizador de habilitação deve ser valores de bit (sinalizador). O qualificador ValueDescriptions é opcional, mas você deve usá-lo para fornecer descrições para cada valor possível. As descrições são usadas quando alguém chama as funções TdhEnumerateProviderFieldInformation e TdhQueryProviderFieldInformation para obter o nível possível e habilitar valores de sinalizadores (palavras-chave) para o provedor.

O exemplo a seguir mostra uma classe de provedor que especifica o nível possível e habilita valores de sinalizadores.

[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;
};