Definizione di 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 in 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 (maschera di bit 0xFFFF000000000000) sono definiti da Microsoft. Per le definizioni delle parole chiave definite da Microsoft, vedere winmeta.h o winmeta.xml nella cartella include Windows Kits.

I provider usano parole chiave per classificare tipi diversi di eventi. Ad esempio, è possibile definire la parola chiave bit 0 (valore parola chiave 0x1) come categoria letta e quindi applicare la parola chiave letta a qualsiasi evento che esegue un'operazione di lettura, ad esempio la lettura da un file o un registro di sistema. I consumer possono quindi usare i valori di bit della parola chiave per filtrare per classificazioni diverse di eventi. Ad esempio, il consumer potrebbe impostare la proprietà MatchAnyKeyword della sessione di raccolta eventi su 0x1 per far sì che la sessione raccolga 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 relativo 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 gli eventi corrispondenti al caso "MatchAnyKeyword", l'evento viene scritto solo se tutti i bit nella maschera "MatchAllKeyword" esistono nella maschera di bit della parola chiave 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 = 0x2) e un secondo evento che specifica una parola chiave di lettura (bit 0 = 0x1) e una parola chiave di accesso remoto (bit 2 = 0x4), è possibile impostare la maschera di bit "MatchAnyKeyword" della sessione eventi su 0x1 (lettura) e la maschera di bit "MatchAllKeyword" su 0x0 (nessuno) per ricevere tutti gli eventi di lettura, oppure è possibile impostare la maschera di bit "MatchAnyKeyword" su 0x1 e la maschera di bit "MatchAllKeyword" su 0x3 (lettura + locale) per ricevere solo letture locali.

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

È necessario specificare gli attributi del nome della parola chiave e della maschera . La maschera deve essere un numero 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 sono definiti da Microsoft (vedere winmeta.h o winmeta.xml) e non possono essere usati nell'elemento parola chiave.

Gli attributi del simbolo e del messaggio 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>