イベント トレース セッションの構成と開始
イベント トレース セッションを構成するには、EVENT_TRACE_PROPERTIES 構造体を使用してセッションのプロパティを指定します。 EVENT_TRACE_PROPERTIES 構造体に割り当てるメモリは、メモリ内の構造に続くセッションとログ ファイルの名前も含めるのに十分な大きさである必要があります。
セッションのプロパティを指定した後、StartTrace 関数を呼び出してセッションを開始します。 関数が成功した場合、SessionHandle パラメーターにはセッション ハンドルが格納され、LoggerNameOffset プロパティにはセッションの名前へのオフセットが含まれます。
セッションにイベントを記録するプロバイダーを有効にするには、EnableTrace 関数を呼び出して、クラシック プロバイダーと EnableTraceEx 関数を有効にして、manifest ベースの プロバイダーを有効にします。 Windows 8.1、Windows Server 2012 R2 以降の特定の条件でイベントをセッション フィルター処理に記録するプロバイダーを有効にするには、EnableTraceEx2 関数を呼び出します。
さらに、TraceSetInformation 関数を呼び出して、イベントに関する追加情報をトレースすることもできます。 TraceSetInformation イベントの拡張データ セクションに追加のトレース情報を格納し、トレース バージョン情報や、システムに現在登録されているプロバイダーなどの情報を含めることができます。 詳細については、「追加のイベント トレース データの取得」を参照してください。
最大 8 つのトレース セッションで、同じ manifest ベースのプロバイダーからイベントを有効にして受信できます。 ただし、クラシック プロバイダーを有効にできるトレース セッションは 1 つだけです。 複数のトレース セッションでクラシック プロバイダーを有効にしようとすると、2 番目のセッションでプロバイダーが有効になると、最初のセッションはイベントの受信を停止します。 たとえば、セッション A がプロバイダー 1 を有効にした後、セッション B がプロバイダー 1 を有効にした場合、セッション B のみがプロバイダー 1 からイベントを受信します。
3 つの関数のいずれかを使用してプロバイダーを有効にすることができますが、matchAllKeyword 値を指定したり、イベントに含める拡張データ項目を指定したり、プロバイダー定義のフィルター データを提供したりできないため、EnableTrace を使用してマニフェスト ベースのプロバイダーを有効にすると機能が失われる可能性があります。 詳しくは、各関数の「解説」をご覧ください。
Windows 8.1、Windows Server 2012 R2 以降では、イベント ペイロード、スコープ、スタック ウォーク フィルターは、EnableTraceEx2 関数と ENABLE_TRACE_PARAMETERS および EVENT_FILTER_DESCRIPTOR 構造体で使用して、ロガー セッション内の特定の条件をフィルター処理できます。 イベント ペイロード フィルターの詳細については、TdhCreatePayloadFilter および TdhAggregatePayloadFilters 関数と ENABLE_TRACE_PARAMETERS、 EVENT_FILTER_DESCRIPTOR、および PAYLOAD_FILTER_PREDICATE 構造体を参照してください。
マニフェスト ベースのプロバイダーを有効にするために使用されるレベルとキーワードを決定するには、次のいずれかのコマンドを使用します。
- Logman query provider-name
- Wevtutil gp provider-name
コマンドにはレベルとキーワードのみが一覧表示され、プロバイダーは潜在的なコントローラーのフィルター データ要件を文書化する必要があります。
マニフェスト ベースのプロバイダーを列挙するには、Wevtutil ep を使用します。
従来のプロバイダーの場合、サポートする重大度レベルや有効化フラグを文書化し、潜在的なコントローラーに提供するのはプロバイダーの責任です。 プロバイダーを任意のコントローラーで有効にする場合、プロバイダーは重大度レベルと有効化フラグとして 0 を受け入れ、0 をデフォルトのログ記録 (それが何であれ) を実行する要求として解釈する必要があります。
プロバイダー自体を登録する前または後に、プロバイダーを有効にすることができます。 プロバイダーを有効にすると、ETW はプロバイダーのコールバック関数を呼び出します。 プロバイダーが登録されていない場合、ETW は自身を登録した後、プロバイダーのコールバック関数を呼び出します。
また、EnableTrace 関数を使用して、プロバイダーを無効にしたり (イベントがセッションにログ記録されないようにしたり)、プロバイダーのログ レベルを更新したり、フラグを有効にしたりすることもできます。 EnableTraceEx 関数を使用すると、プロバイダーを無効にしたり、レベル、キーワード、拡張データ、およびフィルター データを更新したりできます。 EnableTrace または EnableTraceEx 関数を呼び出すたびに、ETW はプロバイダーのコールバック関数を呼び出します。 セッションがプロバイダーを無効にするまで、プロバイダーはセッションに対して有効なままになります。
イベントの収集後にトレース セッションを停止するには、ControlTrace 関数を呼び出し、EVENT_TRACE_CONTROL_STOP を制御コードとして渡します。 停止するセッションを指定するには、前の呼び出しから取得したイベント トレース セッション ハンドルを、StartTrace 関数または以前に開始されたセッションの名前に渡します。 セッションを停止する前に、必ずすべてのプロバイダーを無効にしてください。 最初にプロバイダーを無効にする前にセッションを停止した場合、ETW はプロバイダーを無効にし、プロバイダーの制御コールバック関数を呼び出そうとします。 プロバイダーを無効にしたり、ControlTrace 関数を呼び出したりせずにセッションを開始したアプリケーションが終了した場合、プロバイダーは有効なままです。
ControlTrace が成功した場合、セッション プロパティが更新され、最終的なプロパティ値が反映され、イベント トレース セッションの統計情報が実行されます。
イベント トレース セッションを開始する例については、次を参照してください。
- セッションを作成し、マニフェスト ベースのプロバイダーを有効にする例 - トレース セッションを開始し、マニフェスト ベースのプロバイダーを有効にして、プロバイダーを無効にしてから、セッションを停止します。
トレース セッションの開始の詳細については、次のいずれかを参照してください。
- SystemTraceProvider セッションの構成と開始を参照してください。
- NT カーネル ロガー セッションの構成と開始
- AutoLogger セッションの構成と開始
- グローバル ロガー セッションの構成と開始
- プライベート ロガー セッションの構成と開始
関連トピック
-
SystemTraceProvider セッションの構成と開始を参照してください。