PEVENT_RECORD_CALLBACK コールバック関数 (evntrace.h)

  • [アーティクル]

コンシューマーは、トレース処理セッションからイベントを受信するために、このコールバックを実装します。

PEVENT_RECORD_CALLBACK型は、このコールバック関数へのポインターを定義します。 EventRecordCallback は、アプリケーション定義関数名のプレースホルダーです。

構文

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

パラメーター

[in] EventRecord

イベント情報を含む EVENT_RECORD 構造体へのポインター。

戻り値

なし

解説

ETW が呼び出してイベントを配信する関数を指定するには、OpenTrace 関数に渡すEVENT_TRACE_LOGFILE構造体の EventRecordCallback、Context、および ProcessTraceMode メンバーを設定します。

  • EventRecordCallback をコールバック関数のアドレスに設定します。
  • [コンテキスト] を、コールバックに提供される各EVENT_RECORDの UserContext フィールドに含める必要がある値に設定します。
  • ProcessTraceMode を、トレースの処理中に使用するフラグに設定します。 EventRecordCallback を使用するには、ProcessTraceMode 値にPROCESS_TRACE_MODE_EVENT_RECORDを含める必要があります。

Note

EventRecordCallback 関数が ProcessTrace から文字化けしたデータを受信している場合は、OpenTrace に提供された構造体の EVENT_TRACE_LOGFILE フィールドでProcessTraceMode指定されたフラグをダブルチェックします。 EVENT_TRACE_LOGFILEの EventCallback フィールドと EventRecordCallback フィールドは、共用体のメンバーと重複しています。 フィールドに フラグがProcessTraceModePROCESS_TRACE_MODE_EVENT_RECORD含まれている場合、ProcessTrace は EventRecordCallback 関数シグネチャを使用してコールバックを呼び出します。 それ以外の場合、 ProcessTrace は EventCallback 関数シグネチャを使用してコールバックを呼び出します。

OpenTrace を使用してトレース処理セッションを作成した後、ProcessTrace 関数を呼び出してイベントの受信を開始します。

ProcessTrace は、トレースからのイベントの処理を開始するときに、ログに記録されたイベントのデータではなく、トレース (メタデータ) に関するデータを含む 1 つ以上の合成イベントを使用してコールバックを呼び出す場合があります。 これらの合成イベントには 、EventHeader.ProviderId が に EventTraceGuid 設定され、合成イベントの内容に基づいて EventHeader.EventDescriptor.Opcode が設定されます。 たとえば、各トレース ファイルからの最初のイベントは、 TRACE_LOGFILE_HEADER情報を 含む Opcode 0 を含む合成イベントになります。

受信する他のすべてのイベントには、プロバイダー固有のイベント データが含まれます。 受信したイベントの種類を決定するには、EVENT_RECORDの EventHeader.ProviderId メンバーと EventHeader.EventDescriptor メンバーを使用します。

  • イベントが既知のプロバイダーからのものであり、データのレイアウトがわかっている場合は、独自のシステムを使用してイベントをデコードできます。
  • EventHeader.Flags フィールドに フラグがEVENT_HEADER_FLAG_TRACE_MESSAGE含まれている場合、イベントは WPP メッセージです。 適切なデコード情報 (TMF または PDB ファイル) が使用可能な場合は、 TdhGetProperty または TdhGetWppProperty を使用してイベントをデコードできます。
  • それ以外の場合、イベントは MOF ベース、マニフェスト ベース、または TraceLogging イベントである可能性があります。 適切なデコード情報が使用可能な場合は、 TdhGetEventInformation を使用してイベントをデコードできます。
    • イベントで MOF ベースのデコードが使用されている場合、 TdhGetEventInformation はシステムの WMI データ ストアでイベントデコード情報を検索します。
    • イベントでマニフェスト ベースのデコードが使用されている場合、 TdhGetEventInformation は、システムの登録済みマニフェスト、または TdhLoadManifest または TdhLoadManifestFromBinary によってプロセスごとのデコード コンテキストに読み込まれたマニフェストまたはバイナリ内のイベント デコード情報を検索します。
    • イベントで TraceLogging ベースのデコードが使用されている場合、 TdhGetEventInformation は イベント内からのデコード情報を使用します。

ほとんどの場合、イベントは発生した順序 (タイムスタンプの順序) でコールバックに配信されます。 ただし、状況によっては、イベントが元の順序で配信されない場合があります。

  • トレースがセッション タイムスタンプにシステム時間を使用している場合 (つまり、トレース セッションが 2 に設定された状態で properties.Wnode.ClientContext 開始されました)、セッションがイベントを収集している間にシステム クロックが後方に調整されている場合、一部のイベントは順序外で配信される可能性があります。 これを回避するには、ClientContext を 0 に設定して、既定のタイムスタンプ (QPC 時刻) を取得します。
  • 不正確なクロックのタイムスタンプを使用してトレースが収集された場合、異なる CPU から同じタイムスタンプを持つイベントが順不同で配信される可能性があります。 これは、システム時刻のティックが原因で、トレースがセッション タイムスタンプにシステム時刻を使用する場合に最も頻繁に発生します。 この問題は、LogFileMode フラグで とのセッションEVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGを開始することで回避できますが、トレースのパフォーマンスに大きな悪影響を及ぼす可能性があります。 Windows 10以降: システム タイム クロックの種類では、GetSystemTimePreciseAsFileTime を使用して、この問題の可能性を減らします。
  • トレースが破損している場合、ファイル内で予想されるタイムスタンプ 規則を保持しない低レベルの API を使用して生成された場合、またはイベントの書き込み時にタイムスタンプオーバーライド オプションを使用した場合、一部のイベントが順序どおりに配信される可能性があります。

技術的な詳細: イベントはバッファーに格納されます。 各バッファーは、バッファー ストリーム (通常は CPU ごとに 1 つのストリーム) に割り当てられます。 ProcessTrace 実装では、バッファー内のすべてのイベントがタイムスタンプで並べ替えられていることを前提としており、各バッファーには、そのバッファーのストリーム内の他のバッファーのスパンと重複しない 1 つの期間のイベントが含まれていることを前提としています。 これらの前提条件が満たされない場合、ProcessTraceはイベントを順序外で配信する可能性があります。

リアルタイム トレース収集セッションにトレース処理セッションが関連付けられていない場合、収集されたイベントは、バッファーがいっぱいになるまでシステムによってバッファーされます。 トレース処理セッションがリアルタイムトレース収集セッションに接続すると、トレース処理セッションはセッションの合成イベント、バッファーされたイベントを受信し、新しく生成されたリアルタイム イベントの受信を開始します。 2 つ目のリアルタイム処理セッションが同じトレース 収集セッションに接続すると、合成イベントと新しく生成されたリアルタイム イベントが受信されます (2 番目のトレース処理セッションは古いイベントを受信しません)。

重要

リアルタイム セッションからイベントを処理するときに、処理コールバックが各イベントの処理に時間がかかりすぎて、イベントの到着が早すぎると、処理が遅くなります。 システムはデータ損失を防ぐためにイベントをバッファー処理しますが、これによりシステム リソースの使用量 (メモリやディスクの使用量など) が増加します。 この問題を回避するには、セッション フィルター (各プロバイダーのレベルフィルターやキーワード (keyword) フィルターなど) を使用して受信イベントのレートを減らし、完全な処理を必要としないイベントをスキップするためにコールバックで早期フィルター処理を行い、処理スレッドをブロックしないようにできるだけ早く戻るようにコールバックを最適化します。

イベント データの解釈の詳細については、「イベントの 使用 」および 「TDH を使用したイベント データの取得」を参照してください。

要件

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

関連項目

BufferCallback

イベントの使用

TDH を使用したイベント データの取得

EVENT_TRACE_LOGFILE

OpenTrace

ProcessTrace