EventWriteEx 関数 (evntprov.h)

アクティビティ ID、オプションの関連アクティビティ ID、セッション フィルター、および特別なオプションを使用して ETW イベントを書き込みます。

構文

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

パラメーター

[in] RegHandle

プロバイダーの登録ハンドル。 ハンドルは EventRegister から取得されます。 生成されたイベントでは、ハンドルに関連付けられている ProviderId が使用されます。

[in] EventDescriptor

ID 、バージョン、レベル、キーワード、チャネル、オペコード、タスクなどのイベント情報 (メタデータ) を含むEVENT_DESCRIPTOR。

[in] Filter

64 ビットビットマスク値。 各セット ビットは、このイベントを特定のトレース セッションから除外する必要があることを示します。

Filter パラメーターは、EnableCallback の FilterData に基づいてカスタム イベント フィルター処理を実行するイベント プロバイダーで使用されます。

カスタム イベント フィルターをサポートしていない場合、またはイベントをすべてのトレース セッションに書き込む必要がある場合は、[ フィルター ] を 0 に設定します。 それ以外の場合は、 Filter をイベントを受信しないセッションの識別子のビットごとの OR に設定します。

[in] Flags

通常のイベント処理では 、フラグ を 0 に設定します。

特殊なイベント処理のために、フラグをEVENT_WRITE_FLAG値の組み合わせに設定します。

• EVENT_WRITE_FLAG_INPRIVATE (0x2)

  EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE オプションを設定したロガーからこのイベントを除外する必要があることを示します。

[in, optional] ActivityId

このイベントの 128 ビット アクティビティ ID への省略可能なポインター。 これが NULL 以外の場合、 EventWriteEx はイベントのアクティビティ ID に指定された値を使用します。 これが NULL の場合、 EventWriteEx は現在のスレッドのアクティビティ ID を使用します。

トレース処理ツールでは、イベントのアクティビティ ID を使用して、イベントをアクティビティと呼ばれるグループに整理できます。 アクティビティ ID の詳細については、「 EventActivityIdControl」を参照してください。

[in, optional] RelatedActivityId

このイベントのアクティビティの親である 128 ビットアクティビティ ID へのオプションのポインター。 これが NULL 以外の場合、 EventWriteEx はイベントの関連アクティビティ ID に指定された値を使用します。 これが NULL の場合、イベントには関連するアクティビティ ID はありません。 関連するアクティビティ ID は、通常、アクティビティの START イベント (Opcode = START でログに記録されるアクティビティの最初のイベント) に設定されます。

トレース処理ツールでは、イベントの関連アクティビティ ID を使用してアクティビティ間の関係を決定できます。たとえば、関連アクティビティは新しく開始されたアクティビティの親です。 関連するアクティビティ ID の詳細については、「 EventActivityIdControl」を参照してください。

[in] UserDataCount

UserData 内のEVENT_DATA_DESCRIPTOR構造体の数。 最大数は 128 です。

[in, optional] UserData

UserDataCountの配列EVENT_DATA_DESCRIPTOR、イベントに含めるデータを記述する構造体です。 UserDataCount が 0 の場合、UserData は NULL になる可能性があります。

各 EVENT_DATA_DESCRIPTOR では、イベントに含める 1 つのメモリ ブロックについて説明します。 指定されたブロックは、埋め込みまたは配置なしで連結され、イベント コンテンツが形成されます。 マニフェストベースのデコードを使用する場合、イベントコンテンツはマニフェスト内のイベントに関連付けられたテンプレートで指定されたレイアウトと一致する必要があります。

戻り値

成功した場合 、または エラー コードERROR_SUCCESSを返します。 考えられるエラー コードは次のとおりです。

• ERROR_INVALID_PARAMETER: 1 つ以上のパラメーターが無効です。
• ERROR_INVALID_HANDLE: プロバイダーの登録ハンドルが無効です。
• ERROR_ARITHMETIC_OVERFLOW: イベント サイズが許容最大値 (64 KB - ヘッダー) を超えています。
• ERROR_MORE_DATA: セッション バッファー サイズがイベントに対して小さすぎます。
• ERROR_NOT_ENOUGH_MEMORY: 塗りつぶされたバッファーがディスクにフラッシュしようとしているが、ディスク IO が十分な速度で実行されていない場合に発生します。 これは、ディスクが低速で、イベント トラフィックが多い場合に発生します。 最終的には、空の (空の) バッファーがなくなり、イベントが削除されます。
• STATUS_LOG_FILE_FULL: リアルタイム再生ファイルがいっぱいです。 リアルタイム コンシューマーが再生ファイルからイベントを使用するまで、イベントはセッションに記録されません。

エラー コードは、主にデバッグと診断のシナリオで使用することを目的としています。 ETW イベントを記述できなかった場合でも、ほとんどの運用コードは引き続き実行され、イベントを報告し続ける必要があるため、リリース ビルドでは通常、エラー コードを無視する必要があります。

注釈

ほとんどのイベント プロバイダーは、 EventWriteEx を 直接呼び出しません。 代わりに、ほとんどのイベント プロバイダーは、EventRegister、EventWriteEx、および EventUnregister の呼び出しをラップする ETW フレームワークを使用して実装されます。 たとえば、 イベント マニフェストを記述 し、 メッセージ コンパイラ を使用してイベントの C/C++ コードを生成したり、 TraceLogging を 使用してマニフェストが不要になる場合があります。

EventWriteEx は、ProviderId ( RegHandle から決定)、Level、Keyword、およびその他のイベント特性に基づいて、イベントを適切なトレース セッションにルーティングします。 このイベントを記録しているトレース セッションがない場合、この関数は何も実行せず、 ERROR_SUCCESSを返します。

トレース セッションによって記録されないイベントのパフォーマンスへの影響を軽減するために、 EventEnabled を呼び出して、データを準備して EventWriteEx を呼び出す前に、トレース セッションがイベントを記録しているかどうかを判断できます。

プロバイダーは、セッションがイベント データに基づいてイベントをフィルター処理するために使用するフィルターを定義できます。 コア フィルターは、レベルとキーワードに基づいています。 イベント プロバイダーは、より複雑なフィルターをサポートできます。 イベント プロバイダーは、EnableCallback の FilterData パラメーターからフィルター情報を受信できます。 プロバイダーはフィルターを評価し、EventWriteEx の Filter パラメーターを使用して、特定のトレース セッションがフィルターを渡さなかったため、イベントを受信しないことを示すことができます。

要件

こちらもご覧ください

EventActivityIdControl

EventRegister

EventWrite

EventWriteTransfer

マニフェストベースのイベントの記述。