Definieren von Schlüsselwörtern zum Klassifizieren von Ereignistypen

Eine ETW-Schlüsselwort (keyword) ist eine 64-Bit-Bitmaske, die verwendet wird, um die Mitgliedschaft eines Ereignisses in einer Reihe von Ereigniskategorien anzugeben. Jedes Bit im Schlüsselwort (keyword) entspricht einer Kategorie. Wenn für die Schlüsselwort (keyword) eines Ereignisses ein Bit festgelegt ist, gehört das Ereignis zu der Ereigniskategorie, die diesem Bit entspricht.

Die niedrigen 48 Bits der Schlüsselwort (keyword) (Bitmaske 0x0000FFFFFFFFFFFF) werden vom Ereignisanbieter (dem Autor des Manifests) definiert. Die obersten 16 Bits der Schlüsselwort (keyword) (Bitmaske 0xFFFF000000000000) werden von Microsoft definiert. Die Definitionen der von Microsoft definierten Schlüsselwörter finden Sie winmeta.h unter oder winmeta.xml im Ordner "Windows Kits include".

Anbieter verwenden Schlüsselwörter, um verschiedene Ereignistypen zu klassifizieren. Sie können beispielsweise Schlüsselwort (keyword) Bit 0 (Schlüsselwort (keyword) Wert 0x1) als Lesekategorie definieren und dann die lesebasierte Schlüsselwort (keyword) auf jedes Ereignis anwenden, das einen Lesevorgang ausführt, z. B. das Lesen aus einer Datei oder Registrierung. Consumer können dann die Schlüsselwort (keyword) Bitwerte verwenden, um nach verschiedenen Klassifizierungen von Ereignissen zu filtern. Beispielsweise könnte der Consumer die MatchAnyKeyword-Eigenschaft der Ereignissammlungssitzung auf 0x1 festlegen, damit die Sitzung nur die Ereignisse in der Lesekategorie sammelt.

Eine ETW-Ereignissammlungssitzung kann die Schlüsselwörter (auf die gleiche Weise wie level) verwenden, um die Ereignisse einzuschränken, die der ETW-Dienst in seine Ereignisablaufverfolgungsprotokolldatei schreibt. Eine Ablaufverfolgungssitzung kann den Anbieter mithilfe von zwei Sätzen von Schlüsselwort (keyword) Bitmasken aktivieren: eine "MatchAnyKeyword"-Bitmaske, in der das Ereignis geschrieben wird, wenn eines der Schlüsselwort (keyword) Bits des Ereignisses mit einem der in dieser Maske festgelegten Bits übereinstimmt, und eine Bitmaske "MatchAllKeyword", bei der für die Ereignisse, die dem Fall "MatchAnyKeyword" entsprechen, das Ereignis nur geschrieben wird, wenn alle Bits im "MatchAllKeyword" mask ist in der Schlüsselwort (keyword) Bitmaske des Ereignisses vorhanden.

Wenn der Anbieter z. B. ein Ereignis definiert, das eine Lese-Schlüsselwort (keyword) (Bit 0 = 0x1) und einen lokalen Zugriff Schlüsselwort (keyword) (Bit 1 = 0x2) angibt, und ein zweites Ereignis, das eine Lese-Schlüsselwort (keyword) (Bit 0 = 0x1) und einen Remotezugriffs-Schlüsselwort (keyword) (Bit 2 = ) 0x4 angibt ), können Sie die Bitmaske "MatchAnyKeyword" der Ereignissammlungssitzung auf 0x1 (lesen) und die Bitmaske "MatchAllKeyword" auf 0x0 (keine) festlegen, um alle Leseereignisse zu empfangen, oder Sie können die Bitmaske "MatchAnyKeyword" auf 0x1 und die Bitmaske "MatchAllKeyword" auf 0x3 (Read + local) festlegen, um nur lokale Lesevorgänge zu empfangen.

Verwenden Sie das Schlüsselwort (keyword)-Element, um eine Schlüsselwort (keyword) für Ihren Anbieter zu definieren. Nachdem ein Schlüsselwort (keyword) für den Anbieter definiert wurde, können Sie die Schlüsselwort (keyword) jedem der Ereignisse des Anbieters zuweisen, indem Sie das Keywords-Attribut des Ereigniselements verwenden.

Sie müssen den Namen und die Maskierungsattribute des Schlüsselwort (keyword) angeben. Die Maske muss eine ganze Zahl mit einem Bit zwischen Bit 0 und Bit 47 sein, zmask="256". B. odermask="0x100", um Schlüsselwort (keyword) Bit 8 festzulegen. Die Bits 48 bis 63 werden von Microsoft definiert (siehe winmeta.h oder winmeta.xml) und können nicht im Schlüsselwort (keyword)-Element verwendet werden.

Die Symbol- und Nachrichtenattribute sind optional.

Im folgenden Beispiel wird gezeigt, wie ein Schlüsselwort (keyword) definiert wird.

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