Definindo palavras-chave usadas para classificar tipos de eventos

  • Artigo

Um palavra-chave ETW é uma máscara de bits de 64 bits usada para indicar a associação de um evento em um conjunto de categorias de eventos. Cada bit no palavra-chave corresponde a uma categoria. Se o palavra-chave de um evento tiver um bit definido, o evento pertencerá à categoria de evento correspondente a esse bit.

Os 48 bits baixos do palavra-chave (bitmask 0x0000FFFFFFFFFFFF) são definidos pelo provedor de eventos (o autor do manifesto). Os 16 principais bits do palavra-chave (bitmask 0xFFFF000000000000) são definidos pela Microsoft. Confira winmeta.h ou winmeta.xml na pasta Incluir Kits do Windows para obter as definições das palavras-chave definidas pela Microsoft.

Os provedores usam palavras-chave para classificar diferentes tipos de eventos. Por exemplo, você pode definir palavra-chave bit 0 (palavra-chave valor 0x1) como a categoria de leitura e aplicar o palavra-chave de leitura a qualquer evento que execute uma operação de leitura, como leitura de um arquivo ou registro. Em seguida, os consumidores poderiam usar os valores de bits palavra-chave para filtrar diferentes classificações de eventos. Por exemplo, o consumidor pode definir a propriedade MatchAnyKeyword da sessão de coleta de eventos para 0x1 fazer com que a sessão colete apenas os eventos na categoria de leitura .

Uma sessão de coleção de eventos ETW pode usar as palavras-chave (da mesma forma que usa o nível) para limitar os eventos que o serviço ETW grava em seu arquivo de log de rastreamento de eventos. Uma sessão de rastreamento pode habilitar o provedor usando dois conjuntos de bitmasks palavra-chave: uma máscara de bits "MatchAnyKeyword" em que o evento é gravado se qualquer um dos bits palavra-chave do evento corresponder a qualquer um dos bits definidos nesta máscara, e uma máscara de bits "MatchAllKeyword", em que para os eventos que corresponderam ao caso "MatchAnyKeyword", o evento será gravado somente se todos os bits na máscara "MatchAllKeyword" existirem no evento palavra-chave máscara de bits.

Por exemplo, se o provedor definir um evento que especifica um palavra-chave de leitura (bit 0 = 0x1) e um palavra-chave de acesso local (bit 1 = 0x2), e um segundo evento que especifica um palavra-chave de leitura (bit 0 = 0x1) e um acesso remoto palavra-chave (bit 2 = 0x4), você poderá definir a máscara de bits "MatchAnyKeyword" da sessão de coleta de eventos como 0x1 (leia) e a máscara de bits "MatchAllKeyword" como 0x0 (nenhum) para receber todos os eventos de leitura ou você pode definir a máscara de bits 0x1 "MatchAnyKeyword" como e a máscara de bits "MatchAllKeyword" como 0x3 (leitura + local) para receber somente leituras locais.

Para definir um palavra-chave para seu provedor, use o elemento palavra-chave. Depois que um palavra-chave tiver sido definido para o provedor, você poderá atribuir o palavra-chave a qualquer um dos eventos do provedor usando o atributo de palavras-chave do elemento event.

Você deve especificar os atributos de nome e máscara do palavra-chave. A máscara deve ser um inteiro com um bit definido, entre o bit 0 e o bit 47, como mask="256" ou mask="0x100" para definir palavra-chave bit 8. Os bits 48 a 63 são definidos pela Microsoft (ver winmeta.h ou winmeta.xml) e não podem ser usados no elemento palavra-chave.

Os atributos de símbolo e mensagem são opcionais.

O exemplo a seguir mostra como definir um palavra-chave.

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