TraceEvent 関数 (evntrace.h)

  • [アーティクル]

RegisterTraceGuids ベース ("クラシック") イベント プロバイダーは、TraceEvent 関数を使用して構造化イベントをイベント トレース セッションに送信します。

構文

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

パラメーター

[in] TraceHandle

イベントを記録するイベント トレース セッションを処理します。 プロバイダーは、ControlCallback 実装で GetTraceLoggerHandle 関数を呼び出すときにハンドルを取得します。

[in] EventTrace

EVENT_TRACE_HEADER構造体へのポインター。 イベント固有のデータは、必要に応じて 構造体に追加されます。 ログに記録できる最大のイベントは、64,000 件未満です。 EVENT_TRACE_HEADER構造体の次のメンバーの値を指定する必要があります。

  • [サイズ]
  • Guid または GuidPtr
  • Flags

プロバイダーが提供する情報の複雑さに応じて、次のメンバーの値の指定も検討する必要があります。

  • Class.Type
  • Class.Level

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 一般的なエラーとその原因を次に示します。

  • ERROR_INVALID_FLAG_NUMBER

    EVENT_TRACE_HEADER構造体の Flags メンバーが正しくありません。

  • ERROR_INVALID_HANDLE

    TraceHandle が無効であるか、NT カーネル ロガー セッション ハンドルを指定します。

  • ERROR_NOT_ENOUGH_MEMORY

    セッションの空きバッファーが不足していて書き込みができないことを示します。 これは、イベントの発生頻度が高いとき、ディスク サブシステムに過大な負荷がかかっているか、バッファー数が少なすぎるために発生します。 使用可能なバッファーが増えるまでブロックするのではなく、 TraceEvent によってイベントが破棄されます。

    セッションのバッファーの数およびサイズを増やすか、書き込むイベントの数またはイベントのサイズを減らすことを検討してください。

    Windows 2000: サポートされていません。

  • ERROR_OUTOFMEMORY

    バッファー プールが最大サイズに達していないにもかかわらず、追加のバッファーを割り当てるために使用可能なメモリが不足しており、イベントを受信できるバッファーがないため、イベントは破棄されます。

  • ERROR_INVALID_PARAMETER

    次のいずれかが当てはまります。

    • TraceHandle は NULL です。
    • EventTrace は NULL です。
    • EVENT_TRACE_HEADER構造体の Size メンバーが正しくありません。

  • ERROR_MORE_DATA

    1 つのイベントのデータは、複数のバッファーにまたがることはできません。 トレース イベントは、イベント トレース セッションのバッファーのサイズから EVENT_TRACE_HEADER 構造体のサイズを引いた値に制限されます。

解説

MOF ベースの ETW プロバイダーは、この関数を呼び出します。

Note

ほとんどの開発者はこの関数を呼び出しません。 この API は MOF ベースの ETW をサポートしていますが、マニフェスト ベースの ETW を優先して MOF ベースの ETW は非推奨とされています。 さらに、ほとんどの MOF ベースのプロバイダーは、ETW API を直接呼び出す代わりに、MC.exe によって生成されたラッパー関数を使用します。

プロバイダーがこの関数を呼び出す前に、プロバイダーは

  • RegisterTraceGuids 関数を呼び出して、それ自体とイベント トレース クラスを登録する必要があります。
  • 有効にする必要があります。 コントローラーは EnableTrace 関数を呼び出してプロバイダーを有効にします。

イベントは、ログ ファイルに書き込まれるか、リアルタイムでイベント トレース コンシューマーに送信されるか、またはその両方に書き込まれます。 StartTrace に渡されるEVENT_TRACE_PROPERTIES構造体の LogFileMode メンバーは、イベントの送信先を定義します。

トレース イベントは、発生した順序で書き込まれます。

関連するイベントのセットをトレースするには、 TraceEventInstance 関数を使用します。

Windows Vista では、 EventWrite 関数を使用してイベントをログに記録する必要があります。

例

TraceEvent を使用する例については、「トレース イベント」を参照してください。

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー evntrace.h
Library Advapi32.lib
[DLL] Advapi32.dll

関連項目

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance