Definizione delle parole chiave usate per classificare i tipi di eventi

Una parola chiave ETW è una maschera a 64 bit usata per indicare l'appartenenza di un evento a un set di categorie di eventi. Ogni bit nella parola chiave corrisponde a una categoria. Se la parola chiave di un evento ha un bit impostato, l'evento appartiene alla categoria di eventi corrispondente a tale bit.

I 48 bit bassi della parola chiave (maschera di bit 0x0000FFFFFFFFFFFF) sono definiti dal provider di eventi (autore del manifesto). I primi 16 bit della parola chiave (0xFFFF000000000000 bitmask) sono definiti da Microsoft. Vedere winmeta.h o winmeta.xml in Windows Kits includere la cartella per le definizioni delle parole chiave definite da Microsoft.

I provider usano parole chiave per classificare diversi tipi di eventi. Ad esempio, è possibile definire parole chiave bit 0 (valore 0x1parola chiave ) come categoria di lettura e quindi applicare la parola chiave di lettura a qualsiasi evento che esegue un'operazione di lettura, ad esempio la lettura da un file o un registro. I consumer potrebbero quindi usare i valori di bit della parola chiave per filtrare per classificazioni diverse degli eventi. Ad esempio, il consumer potrebbe impostare la proprietà MatchAnyKeyword della sessione della raccolta eventi per 0x1 rendere la sessione raccogliere solo gli eventi nella categoria di lettura .

Una sessione di raccolta eventi ETW può usare le parole chiave (nello stesso modo in cui usa il livello) per limitare gli eventi scritti dal servizio ETW nel file di log di traccia eventi. Una sessione di traccia può abilitare il provider usando due set di maschere di bit di parole chiave: una maschera di bit "MatchAnyKeyword" in cui l'evento viene scritto se uno dei bit della parola chiave dell'evento corrisponde a uno qualsiasi dei bit impostati in questa maschera, e una maschera di bit "MatchAllKeyword" in cui per tali eventi corrispondenti al caso "MatchAnyKeyword", l'evento viene scritto solo se tutti i bit della maschera "MatchAllKeyword" esistono nella maschera bit bit dell'evento.

Ad esempio, se il provider definisce un evento che specifica una parola chiave di lettura (bit 0 = 0x1) e una parola chiave di accesso locale (bit 1 = ), e un secondo evento che specifica una parola chiave di lettura (bit 0 = 0x2) e una parola chiave di accesso remoto (bit 2 = 0x10x4), è possibile impostare la maschera di bit "MatchAnyKeyword" della raccolta eventi su (lettura) e la maschera di bit "MatchAllKeyword" a 0x00x1 (nessuno) per ricevere tutti gli eventi di lettura, oppure è possibile impostare la maschera di bit "MatchAnyKeyword" su 0x1 e "MatchAllKeyword" su 0x3 (lettura + locale) per ricevere solo letture locali.

Per definire una parola chiave per il provider, usare l'elemento parola chiave . Dopo aver definito una parola chiave per il provider, è possibile assegnare la parola chiave a uno degli eventi del provider usando l'attributo parole chiave dell'elemento evento .

È necessario specificare gli attributi nome e maschera della parola chiave. La maschera deve essere un intero con un set di bit, compreso tra bit 0 e bit 47, ad esempio mask="256" o mask="0x100" per impostare la parola chiave bit 8. I bit da 48 a 63 vengono definiti da Microsoft (vedere winmeta.h o winmeta.xml) e non possono essere usati nell'elemento parola chiave .

Gli attributi dei simboli e dei messaggi sono facoltativi.

Nell'esempio seguente viene illustrato come definire una parola chiave.

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