Definiera nyckelord som används för att klassificera typer av händelser

Ett ETW-nyckelord är en 64-bitars bitmask som används för att ange en händelses medlemskap i en uppsättning händelsekategorier. Varje bit i nyckelordet motsvarar en kategori. Om en händelses nyckelord har en bituppsättning tillhör händelsen den händelsekategori som motsvarar den biten.

De låga 48 bitarna av nyckelordet (bitmask 0x0000FFFFFFFFFFFF) definieras av händelseprovidern (upphovsmannen till manifestet). De 16 översta bitarna av nyckelordet (bitmask 0xFFFF000000000000) definieras av Microsoft. Se winmeta.h eller winmeta.xml i Windows Kits include-mappen för definitionerna av de Microsoft-definierade nyckelorden.

Leverantörer använder nyckelord för att klassificera olika typer av händelser. Du kan till exempel definiera nyckelordsbit 0 (nyckelordsvärde 0x1) som läsa kategori och sedan använda läsa nyckelord för alla händelser som utför en läsåtgärd, till exempel läsning från en fil eller ett register. Konsumenterna kan sedan använda nyckelordsbitvärdena för att filtrera efter olika klassificeringar av händelser. Konsumenten kan till exempel ställa in händelsesamlingssessionens MatchAnyKeyword-egenskap till 0x1 för att göra så att sessionen endast samlar in händelserna i kategorin läsa.

En ETW-händelsesamlingssession kan använda nyckelorden (på samma sätt som den använder nivå) för att begränsa de händelser som ETW-tjänsten skriver till loggfilen för händelsespårning. En spårningssession kan aktivera providern med hjälp av två uppsättningar nyckelordsbitmasker: bitmasken "MatchAnyKeyword" där händelsen skrivs om någon av händelsens nyckelordsbitar matchar någon av de bitar som anges i den här masken. och en "MatchAllKeyword"-bitmask där för de händelser som matchade fallet "MatchAnyKeyword" skrivs händelsen endast om alla bitar i masken "MatchAllKeyword" finns i händelsens nyckelordsbitmask.

Om providern till exempel definierar en händelse som anger ett läsnyckelord (bit 0 = 0x1) och ett nyckelord för lokal åtkomst (bit 1 = 0x2) och en andra händelse som anger ett läsnyckelord (bit 0 = 0x1) och en fjärranslutning åtkomstnyckelord (bit 2 = 0x4), kan du ställa in händelsesamlingssessionens bitmask "MatchAnyKeyword" på 0x1 (läs) och bitmasken "MatchAllKeyword" till 0x0 (ingen) för att ta emot alla läshändelser. eller så kan du ställa in bitmasken "MatchAnyKeyword" på 0x1 och "MatchAllKeyword" till 0x3 (läs + lokal) för att endast ta emot lokala läsningar.

Om du vill definiera ett nyckelord för providern använder du nyckelordet element. När ett nyckelord har definierats för providern kan du tilldela nyckelordet till någon av providerns händelser med hjälp av nyckelord attribut för händelse element.

Du måste ange nyckelordets namn och mask attribut. Masken måste vara ett heltal med en bituppsättning, mellan bit 0 och bit 47, till exempel mask="256" eller mask="0x100" för att ange nyckelordsbit 8. Bit 48 genom 63 definieras av Microsoft (se winmeta.h eller winmeta.xml) och kan inte användas i nyckelordselementet .

-symbolen och -meddelande-attribut är valfria.

I följande exempel visas hur du definierar ett nyckelord.

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