TraceLoggingWrite マクロ (traceloggingprovider.h)

[アーティクル]
03/08/2023

TraceLogging イベントを生成します。

構文

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

パラメーター

[in] hProvider

イベントの書き込みに使用する TraceLogging プロバイダーのハンドル。

[in] eventName

イベントを識別するために使用する短い一意の名前。これは、変数ではなく文字列リテラルである必要があります。文字を埋め込 '\0' むことはできません。

[in, optional] __VA_ARGS__

イベントにフィールドを構成または追加するための最大 99 個の追加パラメーター。各パラメーターは、TraceLoggingLevel、TraceLoggingKeyword、TraceLoggingValue などのトレースログラッパーマクロのいずれかである必要があります。

重要

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

戻り値

なし

解説

TraceLoggingWrite マクロの各呼び出しは、指定されたプロバイダーハンドルを介して ETW にイベントを書き込むのに必要なコードに拡張されます。

TraceLoggingWrite は、指定されたプロバイダーが登録されているかどうかを確認します。プロバイダーが登録されていない場合、 TraceLoggingWrite は何も行いません。
TraceLoggingWrite は、 TraceLoggingProviderEnabled を呼び出すかのように、コンシューマーがイベントをリッスンしているかどうかを確認します。コンシューマーがイベントをリッスンしていない場合、 TraceLoggingWrite は何も行いません。
それ以外の場合、 TraceLoggingWrite は引数で指定されたランタイム式を評価し、結果を保存し、必要なデータをイベントにパックし、 EventWriteTransfer を呼び出してイベントを ETW に送信します。

生成されたイベントは、次のように構築されます。

イベントのプロバイダー ID、プロバイダー名、およびプロバイダーグループは 、hProvider パラメーターから取得されます。
イベントの名前は eventName パラメーターから取得されます。
ユーザーモードでは、イベントのアクティビティ ID はスレッドの暗黙的なアクティビティ ID から取得されます。カーネルモードでは、イベントのアクティビティ ID がGUID_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 などのフィールド引数によって追加されます。詳細については、「トレースログラッパーマクロ」を参照してください。

次に例を示します。

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

の TraceLoggingWrite(hProvider, "EventName", args...) 呼び出しは、次のようなコードへの拡張と考えることができます。

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

注意

各 TraceLoggingWrite マクロは TraceLoggingProviderEnabled を自動的にチェックするため、コンシューマーがプロバイダーからのイベントをリッスンしている場合にのみイベントが書き込まれます。その結果、通常は TraceLoggingProviderEnabled を直接呼び出す必要があります。の args... ランタイム式は、イベントが有効になっている場合にのみ評価されます。ランタイム式は複数回評価されません。

複雑なイベントを生成する場合は、行が長すぎるか、コンパイラがヒープ領域を使い切っていることを示すコンパイラエラーが発生する可能性があります。これは、 TraceLoggingWrite マクロがコンパイラでサポートできるよりも長い行に拡張されるときに発生します。このような場合は、イベントを簡略化する必要があります。

TraceLoggingWrite マクロは、EVENT_DATA_DESCRIPTORの配列を使用して ETW にデータを転送します。 ETW で受け入れられる記述子の最大数は 128 です。各パラメーターでは 0、1、または 2 個の記述子を使用する必要があるため、引数の制限 (99) に達する前にデータ記述子の制限 (128) に達する可能性があります。

重要

大規模なイベントを回避してください。 ETW は、主に小さなイベントを処理するために設計されています。 TraceLoggingWrite は、大きすぎるイベントをサイレントに削除します。イベントのサイズは、イベントのヘッダー (ETW ランタイムによって追加)、メタデータ (プロバイダー名、イベント名、フィールド名、フィールド型)、データ (フィールド値) の合計に基づきます。イベントの合計サイズが 65535 より大きい場合、またはコンシューマーセッションでイベントのサイズよりも小さいバッファーサイズを使用している場合、イベントは記録されません。

TraceLoggingWrite の呼び出しは、pActivityId パラメーターと pRelatedActivityId パラメーターに対して NULL を指定した TraceLoggingWriteActivity の呼び出しと同じです。イベントのアクティビティ ID を指定する必要がある場合は、 TraceLoggingWriteActivity を使用します。

例

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

要件


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

TraceLoggingWrite マクロ (traceloggingprovider.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース