Zpracování manifestu instrumentace

Aplikace a knihovny DLL používají manifest instrumentace k identifikaci jejich zprostředkovatelů instrumentace a událostí, které zprostředkovatelé zapisují. Manifest je soubor XML, který obsahuje prvky, které identifikují vašeho zprostředkovatele. Konvencí je použití .man jako rozšíření manifestu. Manifest musí odpovídat manifestu události XSD. Podrobnosti o schématu viz EventManifest Schema.

Zprostředkovatel instrumentace je jakákoli aplikace nebo knihovna DLL, která volá EventWriteEx, EventWriteStringnebo EventWriteTransfer funkce zápisu událostí do relace trasování událostí tras ování událostí (ETW) nebo kanálu protokolu událostí. Aplikace může definovat jednoho zprostředkovatele instrumentace, který pokrývá všechny události, které zapisuje, nebo může definovat zprostředkovatele pro samotnou aplikaci a samostatného zprostředkovatele pro každou ze svých knihoven DLL. Počet zprostředkovatelů, které aplikace definuje v manifestu, závisí výhradně na tom, jak chce aplikace uspořádat události, které zapisuje.

Výhodou určení zprostředkovatele pro každou knihovnu DLL je, že pak můžete povolit a zakázat jednotlivé zprostředkovatele a tím i události, které vygenerují. Tato výhoda se vztahuje pouze v případě, že je poskytovatel povolen relací trasování ETW. Všechny události, které určují kanál protokolu událostí, se vždy zapisují do daného kanálu.

Manifest musí identifikovat zprostředkovatele a události, které zapisuje, ale ostatní metadata, jako jsou kanály, úrovně a klíčová slova, jsou nepovinná; jestli definujete volitelná metadata, závisí na tom, kdo bude události využívat. Pokud například správci nebo pracovníci podpory využívají události pomocí nástroje, jako je Prohlížeč událostí systému Windows, který čte události z kanálů protokolu událostí, musíte definovat kanály, do kterých jsou události zapsány. Pokud je ale poskytovatel povolen pouze relací trasování událostí pro Windows (ETW), nemusíte definovat kanály.

I když jsou úrovně, úkoly, opcode a metadata klíčových slov volitelné, měli byste je použít k logickému seskupení nebo kontejneru událostí. Seskupení událostí pomáhá příjemcům konzumovat pouze ty události, které je zajímají. Příjemce může například zadat dotaz na všechny události, u kterých je úroveň "kritická" a klíčové slovo je "zapisovat", nebo dotazovat se na všechny události napsané konkrétním úkolem.

cs-CZ: Kromě uživatelů, kteří používají úroveň a klíčová slova ke zpracování konkrétních typů událostí, může relace trasování událostí pro Windows používat metadata úrovně a klíčových slov k omezení událostí, které jsou zapsány do protokolu trasování událostí. Relace může například omezit události pouze na události, u kterých je úroveň chyba nebo kritická a klíčové slovo je "přečteno".

Zprostředkovatel může definovat filtry, které relace používá k filtrování událostí na základě údajů o událostech. Při použití úrovně a klíčových slov ETW určuje, zda je událost zapsána do protokolu. Poskytovatel však s použitím datových kritérií filtru rozhoduje, zda zapíše událost do této relace. Filtry se vztahují pouze v případě, že relace trasování ETW aktivuje vašeho poskytovatele.

Následující části ukazují, jak definovat komponenty manifestu:

• Identifikace poskytovatele
• Definování kanálů, do kterých se události zapisují
• Definování úrovní závažnosti událostí, které poskytovatel zapisuje
• Definování úloh a operací, které váš poskytovatel provádí
• Definování klíčových slov, která klasifikují události, které zprostředkovatel zapisuje
• Definování filtrů, které poskytovatel používá k filtrování událostí, které zapisuje
• Definování map názvů a hodnot, na které se odkazuje z dat šablony
• Definování šablon, které definují data specifická pro události
• Definování událostí, které zprostředkovatel zapisuje

I když můžete manifest instrumentace vytvořit ručně, měli byste zvážit použití nástroje ECManGen.exe, který je součástí složky \Bin sady Windows SDK. Nástroj ECManGen.exe používá grafické uživatelské rozhraní, které vás provede vytvořením manifestu od začátku, aniž byste museli používat značky XML. Znalost informací v této části a v části EventManifest Schema vám pomůže při použití nástroje.

Pokud jako editor XML používáte Visual Studio, můžete do projektu přidat schéma EventManifest (viz nabídka XML), abyste mohli využít intellisense, ověřování vloženého schématu a další funkce, aby bylo psaní manifestu snadné a přesné.

Po napsání manifestu pomocí kompilátoru zpráv ověřte manifest a vygenerujte soubory prostředků a hlaviček, které zahrnete do svého poskytovatele. Další informace naleznete v části Kompilace manifestu instrumentace.

Následující příklad ukazuje kostru plně definovaného manifestu události.

<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 ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>