EventWrite 関数 (evntprov.h)

  • [アーティクル]

現在のスレッドのアクティビティ ID を使用する ETW イベントを書き込みます。

構文

ULONG EVNTAPI EventWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

パラメーター

[in] RegHandle

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

[in] EventDescriptor

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

重要

ProviderId、Level、および Keyword は、イベントをフィルター処理するための主な手段です。 他の種類のフィルター処理も可能ですが、オーバーヘッドははるかに高くなります。 常に 0 以外のレベルを割り当て、すべてのイベントにキーワード (keyword)します。

[in] UserDataCount

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

[in, optional] UserData

イベントに含めるデータを記述する UserDataCountEVENT_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 イベントを記述できなかった場合でも、ほとんどの運用コードは引き続き実行され、イベントを報告し続ける必要があるため、リリース ビルドでは通常、エラー コードを無視する必要があります。

解説

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

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

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

EventWrite は、イベントのアクティビティ ID を現在のスレッドのアクティビティ ID に設定します。 EventWrite には、イベントに関連するアクティビティ ID は含まれません。 別のアクティビティ ID を指定したり、関連するアクティビティ ID を追加したりするには、 EventWriteTransfer を使用します。

EventWrite は、EventWriteEx と同等で、Filter の場合は 0、Flags の場合は 0、ActivityId の場合は NULL、RelatedActivityId の場合は NULL です。

要件

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

関連項目

EventActivityIdControl

EventRegister

EventWriteTransfer

EventWriteEx

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