EVENT_TRACE_HEADER 構造体 (evntrace.h)

  • [アーティクル]

EVENT_TRACE_HEADER構造体には、TraceEvent によって書き込まれるすべてのイベントに共通の標準イベント トレース情報が含まれています。

構文

typedef struct _EVENT_TRACE_HEADER {
  USHORT        Size;
  union {
    USHORT FieldTypeFlags;
    struct {
      UCHAR HeaderType;
      UCHAR MarkerFlags;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
  union {
    ULONG Version;
    struct {
      UCHAR  Type;
      UCHAR  Level;
      USHORT Version;
    } Class;
  } DUMMYUNIONNAME2;
  ULONG         ThreadId;
  ULONG         ProcessId;
  LARGE_INTEGER TimeStamp;
  union {
    GUID      Guid;
    ULONGLONG GuidPtr;
  } DUMMYUNIONNAME3;
  union {
    struct {
      ULONG KernelTime;
      ULONG UserTime;
    } DUMMYSTRUCTNAME;
    ULONG64 ProcessorTime;
    struct {
      ULONG ClientContext;
      ULONG Flags;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME4;
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;

メンバー

Size

イベントの合計バイト数。 Size には、ヘッダー構造のサイズと、ヘッダーに追加されたイベント固有のデータのサイズが含まれます。

入力時には、イベント トレース セッションのバッファーのサイズから 72 (0x48) を引いたサイズより小さいサイズにする必要があります。

出力時には、この数値を計算に使用しないでください。

DUMMYUNIONNAME

DUMMYUNIONNAME.FieldTypeFlags

予約済み。

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType

予約済み。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags

予約済み。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.Version

これは Class のメンバーのロールアップです。 下位バイトには Type が含まれており、次のバイトには Level が含まれており、最後の 2 バイトにはバージョンが含まれます。

DUMMYUNIONNAME2.Class

DUMMYUNIONNAME2.Class.Type

イベントの種類。 プロバイダーは、独自のイベントの種類を定義することも、次の表に示す定義済みのイベントの種類を使用することもできます。

  • EVENT_TRACE_TYPE_CHECKPOINT: Checkpoint イベント。 アクティビティの開始時または終了時ではないイベントに使用します。

  • EVENT_TRACE_TYPE_DC_END: データ収集の終了イベント。

  • EVENT_TRACE_TYPE_DC_START: データ収集開始イベント。

  • EVENT_TRACE_TYPE_DEQUEUE: デキュー イベント。 アクティビティが開始する前にキューに登録されている場合に使用します。 作業項目がキューに登録されている時刻をマークするには、EVENT_TRACE_TYPE_STARTを使用します。 デキュー イベントの種類を使用して、アイテムの作業が実際に開始される時間をマークします。 EVENT_TRACE_TYPE_ENDを使用して、アイテムの作業が完了した時刻をマークします。

  • EVENT_TRACE_TYPE_END: イベントを終了します。 を使用して、マルチステップ イベントの最終的な状態をトレースします。

  • EVENT_TRACE_TYPE_EXTENSION: 拡張機能イベント。 前のイベントの継続であるイベントに使用します。 たとえば、イベント トレースがセッション バッファーに収まらないデータを記録する場合は、拡張イベントの種類を使用します。

  • EVENT_TRACE_TYPE_INFO: 情報イベント。 これが既定のイベントの種類です。

  • EVENT_TRACE_TYPE_REPLY: 応答イベント。 リソースを要求するアプリケーションが複数の応答を受信できる場合に使用します。 たとえば、クライアント アプリケーションが URL を要求し、Web サーバーが複数のファイルを送信して応答した場合、受信した各ファイルは応答イベントとしてマークできます。

  • EVENT_TRACE_TYPE_START: イベントを開始します。 マルチステップ イベントの初期状態をトレースするには、 を使用します。

独自のイベントの種類を定義する場合は、10 から始まる数値を使用する必要があります。 ただし、使用する数値を使用できないようにするものはありません。 イベント トレース クラス GUID で複数のイベントの種類がサポートされている場合、コンシューマーは イベントの種類を使用して、イベントとその内容の解釈方法を決定します。

DUMMYUNIONNAME2.Class.Level

イベントの生成に使用される重大度レベルを定義するプロバイダー定義の値。 値の範囲は 0 から 255 です。 コントローラーは 、EnableTraceEx2 関数を呼び出すときの重大度レベルを指定します。 プロバイダーは、ControlCallback 実装から GetTraceEnableLevel 関数を呼び出して重大度レベルを取得します。 プロバイダーは、 値を使用してこのメンバーを設定します。

ETW は、次の重大度レベルを定義します。 1 より高いレベルを選択すると、下位レベルのイベントも含まれます。 たとえば、コントローラーで TRACE_LEVEL_WARNING (3) が指定されている場合、プロバイダーは TRACE_LEVEL_FATAL (1) イベントと TRACE_LEVEL_ERROR (2) イベントも生成します。

値 意味
TRACE_LEVEL_CRITICAL (1) 異常終了イベントまたは終了イベント
TRACE_LEVEL_ERROR (2) 重大なエラー イベント
TRACE_LEVEL_WARNING (3) 割り当てエラーなどの警告イベント
TRACE_LEVEL_INFORMATION (4) エントリ イベントや終了イベントなどのエラー以外のイベント
TRACE_LEVEL_VERBOSE (5) 詳細なトレース イベント

DUMMYUNIONNAME2.Class.Version

イベントのログ記録に使用しているイベント トレース クラスのバージョンを示します。 イベント トレース クラスのバージョンが 1 つしかない場合は、0 を指定します。 バージョンは、イベント データの解読に使用する MOF クラスをコンシューマーに指示します。

ThreadId

出力時に、イベントを生成したスレッドを識別します。

Windows 2000 では、 ThreadId は ULONGLONG 値であることに注意してください。

ProcessId

出力時に、イベントを生成したプロセスを識別します。

Windows 2000: このメンバーはサポートされていません。

TimeStamp

出力時には、イベントが発生した時刻が格納されます。 解決は、EVENT_TRACE_LOGFILE の ProcessTraceMode メンバーに フラグが含まれているPROCESS_TRACE_MODE_RAW_TIMESTAMP場合を除き、システム時刻です。この場合、解決は、コントローラーがセッションを作成した時点で EVENT_TRACE_PROPERTIES の Wnode.ClientContext メンバーの値に依存します。

DUMMYUNIONNAME3

DUMMYUNIONNAME3.Guid

イベント トレース クラス GUID。 クラス GUID を使用してイベントのカテゴリを識別し、 Class.Type メンバーを使用してイベントのカテゴリ内のイベントを識別できます。

または、 GuidPtr メンバーを使用してクラス GUID を指定することもできます。

Windows XP と Windows 2000: クラス GUID は、 RegisterTraceGuids 関数を使用して以前に登録されている必要があります。

DUMMYUNIONNAME3.GuidPtr

イベント トレース クラス GUID へのポインター。 または、 Guid メンバーを使用してクラス GUID を指定することもできます。

イベントが書き込まれると、ETW はポインターを使用して GUID をイベントにコピーします (GUID はポインターではなくイベントに含まれます)。

このメンバーを使用する場合は、 Flags メンバーにもWNODE_FLAG_USE_GUID_PTRが含まれている必要があります。

DUMMYUNIONNAME4

DUMMYUNIONNAME4.DUMMYSTRUCTNAME

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime

CPU 時間単位でのカーネル モード命令の実行経過時間。 プライベート セッションを使用している場合は、代わりに ProcessorTime メンバーの 値を使用します。 詳細については、「解説」を参照してください。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime

ユーザー モード命令の実行経過時間 (CPU 時間単位)。 プライベート セッションを使用している場合は、代わりに ProcessorTime メンバーの 値を使用します。 詳細については、「解説」を参照してください。

DUMMYUNIONNAME4.ProcessorTime

プライベート セッションの場合、ユーザー モード命令の実行経過時間 (CPU ティック単位)。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext

予約済み。

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags

このメンバーを WNODE_FLAG_TRACED_GUID に設定する必要があり、必要に応じて、次の任意の組み合わせを指定できます。

  • WNODE_FLAG_USE_GUID_PTR: GuidPtr メンバーにクラス GUID が含まれているかどうかを指定します。

  • WNODE_FLAG_USE_MOF_PTR: MOF_FIELD 構造体の配列に、この構造体に追加されたイベント データが含まれているかどうかを指定します。 配列内の要素の数は 、MAX_MOF_FIELDSに制限されます。

注釈

メンバーを設定する前に、この構造体のメモリを必ず 0 に初期化してください。

KernelTime メンバーと UserTime メンバーを使用して、一連の命令の CPU コストをユニット単位で決定できます (値は、ログ記録時にそのスレッドに課金される CPU 使用率を示します)。 たとえば、イベント A とイベント B が同じスレッドによって連続してログに記録され、CPU 使用率が 150 と 175 の場合、イベント A と B の間でそのスレッドによって実行されたアクティビティの CPU 時間単位は 25 (175 から 150) になります。

TRACE_LOGFILE_HEADER構造体の TimerResolution には、CPU 使用率タイマーの解像度が 100 ナノ秒単位で含まれています。 タイマー解決をカーネル時間とユーザー時間の値と共に使用して、一連の命令が使用した CPU 時間を決定できます。 たとえば、タイマーの解像度が 156,250 の場合、25 CPU 時間単位は 0.39 秒 (156,250 * 25 * 100 / 1,000,000,000) です。 これは、イベント A と B の間の命令セットで使用される CPU 時間 (壁時計時間が経過していない) の量です。

ただし、通常、CPU 使用率タイマーの解像度は非常に低くなります (約 10 ミリ秒以上)。 そのため、CPU 使用率の数値を使用して、高い精度のスレッド間での CPU 時間の使用率を考慮することはできません。 むしろ、長期的な統計分析に適しています。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
Header evntrace.h

こちらもご覧ください

EVENT_TRACE

EventCallback

TraceEvent