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 (停止イベント) を持つ最後のイベントのWINEVENT_OPCODE_STOPに Opcode を設定する必要があります。

アクティビティ 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 に対する関数の変更は、関数を呼び出すコンポーネントのアクティビティに干渉します。

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

アクティビティが 1 つのスレッドに限定されない場合や、スレッドのアクティビティ 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++ クラスを TraceLogging アクティビティに使用することもできます。

要件

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

関連項目

EventWriteTransfer