TraceLoggingWriteActivity マクロ (traceloggingprovider.h)
指定したアクティビティ ID を持つ TraceLogging イベントを生成します。
構文
void TraceLoggingWriteActivity(
[in] hProvider,
[in] eventName,
[in, optional] pActivityId,
[in, optional] pRelatedActivityId,
[in, optional] __VA_ARGS__
);
パラメーター
[in] hProvider
イベントの書き込みに使用する TraceLogging プロバイダー のハンドル。
[in] eventName
イベントを識別するために使用する短い一意の名前。 これは、変数ではなく文字列リテラルである必要があります。 文字を埋め込 '\0' むことはできません。
[in, optional] pActivityId
イベントのアクティビティ ID。既定値を使用する場合は NULL。
[in, optional] pRelatedActivityId
イベントの関連アクティビティ ID、または関連するアクティビティ ID がない場合は NULL。
[in, optional] __VA_ARGS__
イベントにフィールドを構成または追加するための最大 99 個の追加パラメーター。 各パラメーターは、TraceLoggingLevel、TraceLoggingKeyword、TraceLoggingValue などのトレース ログラッパー マクロのいずれかである必要があります。
重要
ProviderId、Level、Keyword は、イベントをフィルター処理するための主要な手段です。 他の種類のフィルター処理も可能ですが、オーバーヘッドははるかに高くなります。 常に 0 以外のレベルを割り当て、すべてのイベントにキーワード (keyword)します。
戻り値
なし
解説
TraceLoggingWriteActivity マクロの各呼び出しは、指定されたプロバイダー ハンドルを介して ETW にイベントを書き込むのに必要なコードに拡張されます。
- TraceLoggingWriteActivity は 、指定されたプロバイダーが登録されているかどうかを確認します。 プロバイダーが 登録されていない場合、 TraceLoggingWriteActivity は何も行いません。
- TraceLoggingWriteActivity は、 TraceLoggingProviderEnabled を呼び出すかのように、コンシューマーがイベントをリッスンしているかどうかを確認します。 コンシューマーがイベントをリッスンしていない場合、 TraceLoggingWriteActivity は何も行いません。
- それ以外の場合、 TraceLoggingWriteActivity は 、引数で指定されたランタイム式を評価し、結果を保存し、必要なデータをイベントにパックし、 EventWriteTransfer を呼び出してイベントを ETW に送信します。
生成されたイベントは、次のように構築されます。
- イベントのプロバイダー ID、プロバイダー名、およびプロバイダー グループは 、hProvider パラメーターから取得されます。
- イベントの名前は eventName パラメーターから取得されます。
- イベントのアクティビティ ID は pActivityId パラメーターから取得されます。 pActivityId が NULL の場合、ユーザー モード イベントはスレッドの暗黙的なアクティビティ ID を使用し、カーネル モード イベントはGUID_NULLを使用します。
- イベントの関連アクティビティ ID は 、pRelatedActivityId パラメーターから取得されます。 pRelatedActivityId が NULL の場合、イベントには関連するアクティビティ ID はありません。
- イベントのレベルは 、TraceLoggingLevel 引数から取得されます。 TraceLoggingLevel 引数が存在しない場合、イベントのレベルは 5 (WINEVENT_LEVEL_VERBOSE) になります。 複数の TraceLoggingLevel 引数が存在する場合は、最後の引数が使用されます。 効果的なイベント フィルター処理を有効にするには、常にすべてのイベントに意味のある 0 以外のレベルを割り当てます。
- イベントのキーワード (keyword)は、TraceLoggingKeyword 引数から取得されます。 引数 TraceLoggingKeyword がない場合、イベントのキーワード (keyword)は 0 (NONE) になります。 複数の TraceLoggingKeyword 引数が存在する場合、値は一緒に OR になります。 有効なイベント フィルター処理を有効にするには、常にすべてのイベントに意味のある 0 以外のキーワード (keyword)を割り当てます。
- その他のイベント属性は、 TraceLoggingOpcode、 TraceLoggingDescription、 TraceLoggingEventTag、 TraceLoggingChannel などの引数によって設定できます。
- イベント フィールドは 、TraceLoggingStruct を使用してグループ化できます。
- イベント フィールドは、 TraceLoggingValue、TraceLoggingInt32、TraceLoggingHResult、TraceLoggingString などのフィールド引数によって追加されます。詳細については 、「トレース ログ ラッパー マクロ 」を参照してください。
次に例を示します。
TraceLoggingWriteActivity(
g_hProvider,
"MyEvent1",
&myActivityGuid,
NULL, // no related activity ID
TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.
の TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) 呼び出しは、次のようなコードへの拡張と考えることができます。
if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
static const metadata = { GetMetadataFromArgs(args...) };
EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}
注意
各 TraceLoggingWriteActivity マクロは TraceLoggingProviderEnabled を自動的にチェックするため、コンシューマーがプロバイダーからのイベントをリッスンしている場合にのみイベントが書き込まれます。 その結果、通常は TraceLoggingProviderEnabled を直接呼び出す必要があります。 の args... ランタイム式は、イベントが有効になっている場合にのみ評価されます。 ランタイム式は複数回評価されません。
複雑なイベントを生成する場合は、行が長すぎるか、コンパイラがヒープ領域を使い切っていることを示すコンパイラ エラーが発生する可能性があります。 これは、 TraceLoggingWriteActivity マクロがコンパイラでサポートできる行より長い行に拡張されるときに発生します。 このような場合は、イベントを簡略化する必要があります。
TraceLoggingWriteActivity マクロは、EVENT_DATA_DESCRIPTORの配列を使用して ETW にデータを転送します。 ETW で受け入れられる記述子の最大数は 128 です。 各パラメーターでは 0、1、または 2 個の記述子を使用する必要があるため、引数の制限 (99) に達する前にデータ記述子の制限 (128) に達する可能性があります。
重要
大規模なイベントを回避してください。 ETW は、主に小さなイベントを処理するために設計されています。 TraceLoggingWriteActivity は、大きすぎるイベントをサイレントに削除します。 イベントのサイズは、イベントのヘッダー (ETW ランタイムによって追加)、メタデータ (プロバイダー名、イベント名、フィールド名、フィールド型)、データ (フィールド値) の合計に基づきます。 イベントの合計サイズが 65535 より大きい場合、またはコンシューマー セッションでイベントのサイズよりも小さいバッファー サイズを使用している場合、イベントは記録されません。
TraceLoggingWrite の呼び出しは、pActivityId パラメーターと pRelatedActivityId パラメーターに対して NULL を指定した TraceLoggingWriteActivity の呼び出しと同じです。 イベントのアクティビティ ID を指定する必要がある場合は、 TraceLoggingWriteActivity を使用します。
ActivityId パラメーターと RelatedActivityId パラメーターのセマンティクスについては、「EventWriteTransfer」を参照してください。
ETW でのアクティビティの記述については、「 EventActivityIdControl 」を参照してください。
トレース ログ ETW アクティビティの管理に役立つ C++ クラスの TraceLoggingActivity に関するページを参照してください。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | traceloggingprovider.h |
| Library | Advapi32.lib |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示