EventActivityIdControl 関数 (evntprov.h)

ETW イベントで使用するアクティビティ識別子を作成、クエリ、および設定します。

構文

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

パラメーター

[in] ControlCode

実行する操作を指定するコントロール コード。

• EVENT_ACTIVITY_CTRL_GET_ID

  ActivityId パラメーターを現在のスレッドのアクティビティ ID の値に設定します。

• EVENT_ACTIVITY_CTRL_SET_ID

  現在のスレッドのアクティビティ ID を ActivityId パラメーターの値に設定します。

• EVENT_ACTIVITY_CTRL_CREATE_ID

  ActivityId パラメーターを、新しく生成されたローカル固有のアクティビティ ID の値に設定します。

• EVENT_ACTIVITY_CTRL_GET_SET_ID

  ActivityId パラメーターと現在のスレッドのアクティビティ ID の値を入れ替えます。 (現在のスレッドのアクティビティ ID の値を保存し、現在のスレッドのアクティビティ ID を ActivityId パラメーターの値に設定してから、 ActivityId パラメーターを保存された値に設定します)。

• EVENT_ACTIVITY_CTRL_CREATE_SET_ID

  ActivityId パラメーターを現在のスレッドのアクティビティ ID の値に設定し、現在のスレッドのアクティビティ ID を、新しく生成されたローカル固有のアクティビティ ID の値に設定します。

[in, out] ActivityId

128 ビットのアクティビティ ID を含むバッファーへのポインター。 このバッファーは、 ControlCode パラメーターの値に応じて、読み取り元または書き込み可能です。

戻り値

成功した場合 は、ERROR_SUCCESS を返します。

注釈

EventWrite API のいずれかを使用して書き込まれた ETW イベントには、128 ビットの "アクティビティ ID" フィールドが含まれ、必要に応じて 128 ビットの "関連アクティビティ ID" フィールドを含めることができます。 トレース処理ツールでは、これらのフィールドの値を使用して、イベントをアクティビティと呼ばれるグループに整理できます。

• アクティビティ ID が 0 ( GUID_NULL) のすべてのイベントは、どのアクティビティにも含まれていないと見なされます。
• 特定の 0 以外のアクティビティ ID を持つすべてのイベントは、同じアクティビティの一部であると見なされます。
• アクティビティの開始を示すために、プロバイダーは、特定の 0 以外のアクティビティ ID (開始イベント) を持つ最初のイベントに対して Opcode をWINEVENT_OPCODE_STARTに設定する必要があります。 アクティビティが別のアクティビティ内で論理的に入れ子になっている場合、プロバイダーは 開始 イベントの関連アクティビティ ID フィールドを親アクティビティの ID に設定する必要があります。
• アクティビティの終了を示すために、プロバイダーは、特定の 0 以外のアクティビティ ID (停止イベント) を持つ最後のイベントに対して opcode をWINEVENT_OPCODE_STOPに設定する必要があります。

アクティビティ ID を役立てるには、新しく生成されたアクティビティ ID がローカルに一意である必要があります。つまり、同じ ID をトレース内で 2 回生成することはできません。

EventActivityIdControl を使用してアクティビティ ID を作成できます。これにより、システムが再起動するまで、ローカル システム上のすべてのプロセスで一意であることが保証されるローカル固有の ID が生成されます。 アクティビティ ID として GUID (グローバル一意識別子) を使用することもできます。 UUIDCreate などの API を使用して GUID を作成できます。

ユーザー モード スレッドには、スレッド ローカルの 128 ビット アクティビティ ID 値 (スレッドのアクティビティ ID) があります。 スレッドアクティビティ ID は、スレッドの作成時に 0 ( つまりGUID_NULL) に初期化されます。 スレッド アクティビティ ID は、 EventActivityIdControl を使用して読み取りまたは更新できます。 スレッド アクティビティ ID は、EventWrite によって書き込まれたすべてのイベント、および ActivityId パラメーターが NULL である EventWriteTransfer または EventWriteEx によって書き込まれたすべてのイベントのアクティビティ ID として使用されます。

明示的に指定されたアクティビティ ID の使用

アクティビティが単一のスレッドに限定されていない場合、またはスレッドのアクティビティ ID を上書きする他のコンポーネントからの干渉を回避したい場合は、自動スレッド アクティビティ ID を使用する代わりに、EventWriteTransfer または EventWriteEx の ActivityId フィールドを使用してイベント アクティビティを明示的に指定できます。

マニフェストとメッセージ コンパイラを使用してイベントを書き込む場合、によってMC.exe -um生成されたマクロはスレッドのアクティビティ ID を使用し、によってMC.exe -km生成されたマクロはアクティビティ ID パラメーターをサポートします。 もともと、マクロは -um ユーザー モードでのみ機能し -km 、マクロはカーネル モードでのみ機能するため、ユーザー モード コードでは現在のスレッドのアクティビティ ID のみを使用できました。 ただし、MC.exe バージョン 10.0.17741 以降では、 によって MC.exe -km 生成されるマクロは、ユーザー モードとカーネル モードの両方に使用できるため、 を使用 MC.exe -km して、アクティビティ ID パラメーターを受け入れるマクロを生成できます。 (MC によって生成されたコードでは、イベントの関連アクティビティ ID の設定はサポートされていません)。

TraceLoggingProvider.h を使用してイベントを書き込む場合、TraceLoggingWrite マクロはスレッドのアクティビティ ID を使用し、TraceLoggingWriteActivity はアクティビティ ID と関連アクティビティ ID のパラメーターを受け入れます。 または、 TraceLoggingActivity.h の C++ クラスをトレース ログ アクティビティに使用することもできます。

要件

こちらもご覧ください

EventWriteTransfer