TraceLoggingCustom マクロ (traceloggingprovider.h)

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

カスタムシリアライザーを使用してパックされたフィールドをイベントに追加する TraceLogging ラッパーマクロ。

ほとんどの TraceLogging イベントでは、カスタムシリアライザーを使用する必要はありません。また、TraceLoggingCustom を使用しないでください。

構文

void TraceLoggingCustom(
  [in]            pValue,
  [in]            cbValue,
  [in]            protocol,
  [in]            bSchema,
  [in]            cbSchema,
  [in, optional]  __VA_ARGS__
);

パラメーター

[in] pValue

指定したプロトコルファミリのシリアライザーによって実行時にシリアル化される、フィールドのペイロードへのポインター。

[in] cbValue

フィールドのペイロードのサイズ (バイト単位) は、指定されたプロトコルファミリのシリアライザーによって実行時にシリアル化されます。

[in] protocol

プロトコルファミリ。0 から 4 の Microsoft 定義値、または 5 から 31 のユーザー定義値を指定できます。 Microsoft で定義された値は、で始まる TRACELOGGING_PROTOCOL_マクロによって定義されます。

[in] bSchema

ペイロードをデコードするために必要な情報 (つまりスキーマ) をプロトコル定義形式で含むバイト値のコンマ区切りのリスト。この一覧の値は、コンパイル時定数である必要があります。例: (0x12、0x23、0x34)

[in] cbSchema

bSchema で指定されたバイト値の数。この値はコンパイル時定数である必要があります。

[in, optional] __VA_ARGS__

フィールド定義の省略可能な名前、説明、タグパラメーター。

TraceLoggingCustom は、5、6、7、または 8 個のパラメーターで指定できます。パラメーターが指定されていない場合は、既定値が使用されます。たとえば、TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) は、TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0) と同じです。

[in, optional] name

イベントフィールドに使用する名前。指定する場合、name パラメーターは文字列リテラル (変数ではない) であり、'\0' 文字を含めてはなりません。指定しない場合、イベントフィールド名は pValue に基づいています。
[in, optional] description

イベントフィールドの値の説明。指定した場合、description パラメーターは文字列リテラルである必要があり、 PDB に含まれます。
[in, optional] tags

コンパイル時の定数整数値。値の下位 28 ビットは、フィールドのメタデータに含まれます。この値のセマンティクスは、イベントコンシューマーによって定義されます。イベント処理中に、この値は [EVENT_PROPERTY_INFO タグ] フィールドから取得できます。

戻り値

なし

解説

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...)は、TraceLoggingWrite マクロの呼び出しのパラメーターとして使用できます。各 TraceLoggingCustom パラメーターは、カスタムシリアル化されたフィールドをイベントに追加します。ほとんどの TraceLogging イベントでは、カスタムシリアライザーは使用されず、TraceLoggingCustom を使用しないでください。汎用 ETW デコーダーは、カスタムシリアル化を使用するフィールドをサポートせず、通常はフィールドをTDH_INTYPE_BINARYとして扱います。

デコーダーは、TDH API を使用して TraceLoggingCustom シリアル化されたフィールドにアクセスする必要があります。 TdhGetEventInformation によって返されるTRACE_EVENT_INFO構造体には、ログに記録された TraceLoggingCustom フィールドに関連する 2 つのEVENT_PROPERTY_INFO構造体が含まれます。これらは、一般的な方法で、バイナリフィールド (TDH_INTYPE_BINARY) のEVENT_RECORDの UserData BLOB にあるデータと関連付けます。

2 つのEVENT_PROPERTY_INFO構造体の 1 つ目は、シリアル化されたペイロードの長さ (cbValue) を表す "Length" プロパティです。
2 つ目は、ユーザーのペイロード (pbValue) を参照するプロパティです。 2 番目のプロパティには、PropertyParamLength ("Length" プロパティを参照) と PropertyHasCustomSchema が設定されます。

デコーダーは、PropertyHasCustomSchema が設定されていることを認識し、CustomSchemaOffset のEVENT_PROPERTY_INFOの customSchemaType メンバーを参照する必要があります。これは、プロトコルの種類とプロトコルメタデータが配置されているTRACE_EVENT_INFORMATION内のオフセットです。そこでは、 (擬似構造体) の形式で渡されたメタデータを見つけることができます。

struct _CUSTOM_SCHEMA {
    UINT16 protocolType;
    UINT16 cbSchema;
    BYTE bSchema[cbSchema];
};

PropertyHasCustomSchema フラグを認識するためにこれらの追加の手順を実行せず、代わりに EVENT_PROPERTY_INFO 共用体の nonStructType 部分を参照してイベントをデコードする既存のデコーダーは、ペイロードをTDH_INTYPE_BINARYされたかのようにシームレスに処理します。

例

// Value generated at runtime by serializer:
BYTE rgValue[] = {...};

TraceLoggingWrite(
   g_hProvider,
   "MyEventName",
   TraceLoggingCustom(
      rgValue,
      sizeof(rgValue),
      TRACELOGGING_PROTOCOL_MYPROTOCOL,
      ( 0x0, 0x1, 0x2 ), // Generated at compile-time
      3,
      "MyCustomField"),
   TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
   TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories

要件


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

次の方法で共有

TraceLoggingCustom マクロ (traceloggingprovider.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース