EVENT_TRACE_LOGFILEA 構造体 (evntrace.h)

  • [アーティクル]

EVENT_TRACE_LOGFILE構造体には、トレース データ ソースに関する情報が格納されます。

EVENT_TRACE_LOGFILE構造体は、OpenTrace を呼び出すときに使用されます。 ユーザーは 、 トレース データ ソース (ETL ファイルの名前またはアクティブなリアルタイム ロガー セッションの名前)、トレース処理フラグ、およびトレース データを受信するコールバック関数に関する情報を含むEVENT_TRACE_LOGFILE構造体を提供します。 成功すると、 OpenTrace は構造体の残りのフィールドに入力し、トレース データ ソースに関する詳細を返します。

ProcessTrace は、バッファーを処理するときに、ユーザー定義 BufferCallback をEVENT_TRACE_LOGFILE構造体で呼び出して、イベント処理セッションとバッファーに関する情報を提供します。

構文

typedef struct _EVENT_TRACE_LOGFILEA {
  LPSTR                         LogFileName;
  LPSTR                         LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;

メンバー

LogFileName

処理されるログ ファイルの名前。リアルタイム トレース セッションからデータを処理する場合は NULL 。 OpenTrace を呼び出してログ ファイルのデータを使用する場合は、このメンバーの値を指定します。

OpenTrace を呼び出すときに LoggerName が NULL 以外の場合、LogFileName はNULL である必要があります。

OpenTrace を呼び出す場合、イベントを使用するユーザーには、ファイルを読み取るアクセス許可が必要です。

Note

LogFileName フィールドを介して OpenTrace に提供されるファイル名は、サフィックスを含む完全なファイル名である必要があります。 一部のトレース ファイル作成 API では、ユーザー指定のファイル名にサフィックスを自動的に追加できます。 たとえば、コントローラーがプライベート セッションにイベントをログに記録した場合 (コントローラーは、StartTrace を呼び出すときに EVENT_TRACE_PROPERTIES の LogFileMode メンバーを EVENT_TRACE_PRIVATE_LOGGER_MODE に設定します)、生成された ETL ファイルにはプロセス ID サフィックス (例: ) が含まれます。 mytrace.etl_123 これは、ファイルが EVENT_TRACE_FILE_MODE_NEWFILE モードを使用して作成された場合にも発生します。その場合、生成された ETL ファイルにはシーケンス番号が含まれます。

LoggerName

リアルタイム イベント トレース セッションの名前。ログ ファイルからデータを処理する場合は NULL 。 OpenTrace を呼び出してリアルタイム セッションのデータを使用する場合は、このメンバーの値を指定します。

OpenTrace を呼び出すときに、LogFileName が NULL 以外の場合、LoggerName は NULL である必要があります。

トレース コントローラーが EVENT_TRACE_PROPERTIES の LogFileMode メンバーに EVENT_TRACE_REAL_TIME_MODE フラグを 含める設定 を行っている場合にのみ、イベントをリアルタイム で 使用できます。

管理特権を持つユーザー、パフォーマンス ログ ユーザー グループ内のユーザー、LocalSystem、LocalService、NetworkService として実行されているアプリケーションのみが、リアルタイムでイベントを使用できます。 制限付きユーザーにリアルタイムでイベントを使用する機能を付与するには、イベントをパフォーマンス ログ ユーザー グループに追加するか 、EventAccessControl を呼び出します。

Windows XP と Windows 2000: 誰でもリアルタイム イベントを使用できます。

CurrentTime

出力では、1601 年 1 月 1 日午前 0 時からの 100 ナノ秒間隔の現在の時刻。

BuffersRead

出力時に処理されたバッファーの数。

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

予約済み。 使用しないでください。

DUMMYUNIONNAME.ProcessTraceMode

イベントを処理するためのモード。 モードは、ヘッダー ファイルで evntcons.h 定義されます。 次のモードの 1 つ以上を指定できます。

  • PROCESS_TRACE_MODE_EVENT_RECORD

    新しい EVENT_RECORD 形式でイベントを受信する場合は、このモードを指定します (強くお勧めします)。 新しい形式でイベントを受信するには、 EventRecordCallback メンバーでコールバックを指定する必要があります。 このモードを指定しない場合は、 EventCallback メンバーで指定されたコールバックを使用して、古い形式のイベントを受信します。

    Windows Vista より前: サポートされていません。

  • PROCESS_TRACE_MODE_RAW_TIMESTAMP

    既定では、 ProcessTrace は、イベントの TimeStamp を元の未加工形式 (システム時刻、QPC 時間、または CPU サイクル カウンター) からシステム時刻 (1601 年 1 月 1 日午前 0 時から 100 ナノ秒間隔) に変換します。

    EVENT_HEADERの TimeStamp メンバーにタイム スタンプ値を指定せず、システム時刻に変換EVENT_TRACE_HEADER場合は、PROCESS_TRACE_MODE_RAW_TIMESTAMP フラグを指定します。 このフラグを指定すると、 ProcessTrace は、コントローラーが EVENT_TRACE_PROPERTIES の Wnode.ClientContext メンバーで指定した 元の形式のタイム スタンプ値を残します。

    Windows Vista より前: サポートされていません。

  • PROCESS_TRACE_MODE_REAL_TIME

    リアルタイムでイベントを受信するには、このモードを指定します。 LoggerName が NULL でない場合は、このモードを指定する必要があります。

CurrentEvent

出力 時に、 最後に処理されたイベントを含むEVENT_TRACE構造体。

LogfileHeader

出力時に、 セッション とセッションが実行されたコンピューターに関する一般的な情報を含むTRACE_LOGFILE_HEADER構造体。

BufferCallback

バッファー ETW フラッシュごとにバッファー関連の統計を受け取る BufferCallback 関数へのポインター。 ETW は、バッファー内のすべてのイベントを配信した後、このコールバックを呼び出します。 このコールバックは省略可能です。

BufferSize

出力時には、 には各バッファーのサイズがバイト単位で格納されます。

Filled

出力時には、有効な情報を含むバッファー内のバイト数が格納されます。

EventsLost

使用されていません。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

バッファー内の各イベントに対して ETW が呼び出す EventCallback 関数へのポインター。 このフィールドは、 ProcessTraceMode フィールドに フラグが含 PROCESS_TRACE_MODE_EVENT_RECORD まれていない場合にのみ使用されます。

Note

ProcessTraceMode フィールドに フラグが含まれているPROCESS_TRACE_MODE_EVENT_RECORD場合、EventCallback フィールドは EventRecordCallback として扱われます。 EventCallback が ProcessTrace から文字化けしたデータを受信している場合は、ProcessTraceMode フィールドに フラグがPROCESS_TRACE_MODE_EVENT_RECORD含まれていないことを確認します。

ヒント

新しいコードでは 、EventCallback の代わりに EventRecordCallback を使用する必要があります。 EventRecordCallback は、より完全なイベント情報を含むEVENT_RECORDを受け取り、TdhGetEventInformation などのデコード API で使用でき、コールバックで使用できるコンテキスト ポインターを持ちます。

DUMMYUNIONNAME2.EventRecordCallback

バッファー内の各イベントに対して ETW が呼び出す EventRecordCallback 関数へのポインター。 このフィールドは、 ProcessTraceMode フィールドに フラグが PROCESS_TRACE_MODE_EVENT_RECORD 含まれている場合にのみ使用されます。

Note

ProcessTraceMode フィールドに フラグが含PROCESS_TRACE_MODE_EVENT_RECORDまれていない場合、EventRecordCallback フィールドは EventCallback として扱われます。 EventRecordCallback が ProcessTrace から文字化けしたデータを受信している場合は、ProcessTraceMode フィールドに フラグが含まれていることをPROCESS_TRACE_MODE_EVENT_RECORD確認します。

Windows Vista より前: サポートされていません。

IsKernelTrace

出力時に、このメンバーが TRUE の場合、イベント トレース セッションは NT カーネル ロガーです。 それ以外の場合は、別のイベント トレース セッションです。

Context

OpenTrace を呼び出すときにコンシューマーが指定できるコンテキスト データ。 コンシューマーが EventRecordCallback を使用してイベントを使用する場合、ETW は、EVENT_RECORD構造体の UserContext メンバーをこの値に設定します。

Windows Vista より前: サポートされていません。

注釈

イベント コンシューマーは次の手順を実行する必要があります。

  1. この構造体のメモリを 0 に初期化します。
  2. ETL ファイルから読み取る場合は、 LogFileName をファイルのパスに設定します。 それ以外の場合 (つまり、リアルタイム セッションから読み取る場合)、 LoggerName を セッションの名前に設定し、 ProcessTraceMode を に PROCESS_TRACE_MODE_REAL_TIME設定します。
  3. EventRecordCallback (推奨) を使用している場合は、EventRecordCallback をイベント レコード コールバック関数のアドレスに設定し、Context をコールバックに指定する値に設定し、ProcessTraceMode に追加PROCESS_TRACE_MODE_EVENT_RECORDします。 それ以外の場合 (つまり 、EventCallback を使用している場合)、 EventCallback をイベント コールバック関数のアドレスに設定します。
  4. 各バッファーの処理後にコールバックが必要な場合は、 BufferCallback をバッファー コールバック関数のアドレスに設定します。
  5. 処理されたタイムスタンプの代わりに元の生タイムスタンプ データが必要な場合は、ProcessTraceMode に を追加PROCESS_TRACE_MODE_RAW_TIMESTAMPします。
  6. OpenTrace を呼び出します。 成功した場合、 OpenTrace 関数はこの構造体のメンバーにトレース データ ソースからの情報を入力します。
  7. OpenTrace によって返されるハンドルを使用して ProcessTrace を呼び出します。
    • ProcessTrace は、イベントごとにイベント コールバック関数を呼び出します。
    • ProcessTrace は、各バッファーを終了した後にバッファー コールバック関数 (指定されている場合) を呼び出し、トレース処理の状態情報を 含むEVENT_TRACE_LOGFILE 構造体のインスタンスを含めます。
  8. トレース処理が完了したら、 CloseTrace を呼び出して、 OpenTrace によって返されたハンドルを閉じます。

Note

evntrace.h ヘッダーは、unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとしてEVENT_TRACE_LOGFILEを定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

BufferCallback

EventRecordCallback

OpenTrace