インストルメンテーション マニフェストの記述
アプリケーションと DLL では、インストルメンテーション マニフェストを使用して、インストルメンテーション プロバイダーとプロバイダーが書き込むイベントを識別します。 マニフェストは、プロバイダーを識別する要素を含む XML ファイルです。 規則では、マニフェストの拡張機能として .man を使用します。 マニフェストは、イベント マニフェスト XSD に準拠している必要があります。 スキーマの詳細については、「 EventManifest スキーマ」を参照してください。
インストルメンテーション プロバイダーは、 EventWriteEx、 EventWriteString、または EventWriteTransfer 関数を呼び出してイベント トレース (ETW) トレース セッションまたはイベント ログ チャネルにイベントを書き込む任意のアプリケーションまたは DLL です。 アプリケーションは、書き込むすべてのイベントをカバーする 1 つのインストルメンテーション プロバイダーを定義できます。また、アプリケーションのプロバイダーとその DLL ごとにプロバイダーを定義することもできます。 アプリケーションがマニフェストで定義するプロバイダーの数は、アプリケーションが書き込むイベントをどのように整理するかによってのみ異なります。
DLL ごとにプロバイダーを指定する利点は、個々のプロバイダーとそのプロバイダーが生成するイベントを有効または無効にできることです。 この利点は、プロバイダーが ETW トレース セッションによって有効になっている場合にのみ適用されます。 イベント ログ チャネルを指定するすべてのイベントは、常にそのチャネルに書き込まれます。
マニフェストはプロバイダーと、プロバイダーが書き込むイベントを識別する必要がありますが、チャネル、レベル、キーワードなどの他のメタデータは省略可能です。オプションのメタデータを定義するかどうかは、イベントを使用するユーザーによって異なります。 たとえば、管理者またはサポート担当者が、イベント ログ チャネルからイベントを読み取る Windows イベント ビューアー などのツールを使用してイベントを使用する場合は、イベントの書き込み先のチャネルを定義する必要があります。 ただし、プロバイダーが ETW トレース セッションによってのみ有効になる場合は、チャネルを定義する必要はありません。
レベル、タスク、オペコード、キーワードのメタデータは省略可能ですが、それらを使用してイベントを論理的にグループ化またはバケット化する必要があります。 イベントをグループ化すると、コンシューマーは関心のあるイベントのみを使用できます。 たとえば、コンシューマーは、レベルが "クリティカル" で、キーワード (keyword)が "書き込み" であるすべてのイベントに対してクエリを実行したり、特定のタスクによって書き込まれたすべてのイベントに対してクエリを実行したりできます。
特定の種類のイベントを使用するためにレベルとキーワードを使用するコンシューマーに加えて、ETW トレース セッションでは、レベルとキーワード (keyword)メタデータを使用して、イベント トレース ログに書き込まれるイベントを ETW に制限するように ETW に指示できます。 たとえば、セッションでイベントを制限できるのは、level が "error" または "critical" で、キーワード (keyword)が "read" であるイベントのみです。
プロバイダーは、セッションがイベント データに基づいてイベントをフィルター処理するために使用するフィルターを定義できます。 レベルとキーワードを使用すると、ETW はイベントがログに書き込まれるかどうかを判断しますが、フィルターを使用して、プロバイダーはフィルター データ条件を使用してそのセッションにイベントを書き込むかどうかを判断します。 フィルターは、ETW トレース セッションでプロバイダーが有効になっている場合にのみ適用されます。
次のセクションでは、マニフェストのコンポーネントを定義する方法を示します。
- プロバイダーの識別
- イベントの書き込み先となるチャネルの定義
- プロバイダーが書き込むイベントの重大度レベルの定義
- プロバイダーが実行するタスクと操作の定義
- プロバイダーが書き込むイベントを分類するキーワードの定義
- プロバイダーが書き込むイベントをフィルター処理するために使用するフィルターの定義
- テンプレート データが参照する名前/値マップの定義
- イベント固有のデータを定義するテンプレートの定義
- プロバイダーが書き込むイベントの定義
インストルメンテーション マニフェストは手動で作成できますが、Windows SDK の \Bin フォルダーに含まれるECManGen.exe ツールの使用を検討する必要があります。 ECManGen.exe ツールでは、XML タグを使用しなくてもマニフェストをゼロから作成するための GUI が使用されます。 このセクションと EventManifest スキーマ セクションの情報に関する知識を持つことは、ツールを使用する際に役立ちます。
Visual Studio を XML エディターとして使用する場合は、 EventManifest スキーマをプロジェクトに追加して (XML メニューを参照)、Intellisense、インライン スキーマ検証、およびその他の機能を利用して、マニフェストを簡単かつ正確に記述できます。
マニフェストを作成した後、メッセージ コンパイラを使用してマニフェストを検証し、プロバイダーに含めるリソース ファイルとヘッダー ファイルを生成します。 詳細については、「 インストルメンテーション マニフェストのコンパイル」を参照してください。
次の例は、完全に定義されたイベント マニフェストのスケルトンを示しています。
<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>
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示