TRACELOGGING_DEFINE_PROVIDER マクロ (traceloggingprovider.h)

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

トレースログプロバイダーのハンドルを定義します。

構文

void TRACELOGGING_DEFINE_PROVIDER(
  [in]            handleVariable,
  [in]            providerName,
  [in]            providerId,
  [in, optional]  __VA_ARGS__
);

パラメーター

[in] handleVariable

グローバル変数のコンポーネントの名前付け規則 (例: または g_hMyProvider) を使用して、プロバイダーのハンドルに使用する名前。 MyComponentLog

[in] providerName

トレースログプロバイダーの名前を持つ文字列リテラル。この名前は、他のコンポーネントのプロバイダーと競合しないように、organizationとコンポーネントに固有である必要があります。この名前の文字列は、プロバイダーによって生成された各 ETW イベントに含まれるので、比較的短い名前を使用してください。たとえば、や "MyCompany.MyOrganization.MyComponent"のような"MyCompany.MyComponent"名前を使用できます。

これは文字列リテラルである必要があります。変数は使用しないでください。

[in] providerId

かっこ内の 11 個の整数のコンマ区切りリストとして指定された、プロバイダーの ETW コントロール GUID。たとえば、GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} はとして (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5)表されます。

プロバイダー ID には一意の GUID を使用できますが、ETW 名ハッシュアルゴリズムを使用してプロバイダー名から生成された GUID を使用することをお勧めします。プロバイダー ID の生成については、以下を参照してください。

[in, optional] __VA_ARGS__

プロバイダーの省略可能なパラメーター。ほとんどのプロバイダーでは、省略可能なパラメーターを指定する必要はありません。

プロバイダーを ETW プロバイダーグループに関連付ける場合は、 TraceLoggingOptionGroup マクロを追加してプロバイダーのグループ GUID を指定します。それ以外の場合は、パラメーターを __VA_ARGS__ 指定しないでください。

戻り値

なし

解説

トレースログプロバイダーは、イベントを ETW に送信できる接続です。マクロは TRACELOGGING_DEFINE_PROVIDER TraceLogging プロバイダーを定義し、それにアクセスするために使用できるハンドルを作成します。また、プロバイダーの名前や GUID などのプロバイダー情報も記録します。

トレースログプロバイダーのハンドルを定義するには、このマクロを .c または .cpp ファイルで呼び出す必要があります。たとえば、プロバイダーに名前が付けられ MyCompany.MyComponent 、コントロール GUID がである場合は {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} 、コンポーネント内の .c ファイルまたは .cpp ファイルのいずれかに次のコードを追加してプロバイダーを定義します。

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider, // Name of the provider handle
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

上記 TRACELOGGING_DEFINE_PROVIDER のマクロは、次のようなコードのように、プロバイダーハンドル定数を g_hMyProvider 定義すると考えることができます。

const TraceLoggingHProvider g_hMyProvider = ...;

結果のハンドルにはモジュールスコープがあり、定義されている EXE、DLL、または SYS モジュール内の任意の場所で使用できます。必要に応じて TRACELOGGING_DECLARE_PROVIDER マクロ (ヘッダーなど) を使用してハンドルを前方宣言し、コンポーネント内の他の .c ファイルまたは.cpp ファイルで使用できるようにします。

コンポーネントの実行が開始されると、プロバイダーは未登録の状態になります。それを使用してイベントを生成しようとすると、警告なしに無視されます。書き込み呼び出しに応答するには、 TraceLoggingRegister を使用してプロバイダーを登録する必要があります。これは通常、コンポーネントの起動時 (、など) にmainDllMain(DLL_PROCESS_ATTACH)wmainWinMainDriverEntry行われます。コンポーネントのシャットダウン時に、 TraceLoggingUnregister を呼び出してプロバイダーの登録を解除します。

注意

によって定義された TRACELOGGING_DEFINE_PROVIDER プロバイダーハンドルは、モジュールにスコープが設定されます。ハンドルは、EXE、DLL、または SYS ファイル内で必要に応じて使用できますが、モジュールの範囲外で使用しないでください。つまり、同じプロセスで他の DLL に渡さないでください。各 EXE、DLL、または SYS ファイルは、独自のプロバイダーハンドルを使用する必要があり、独自の Register と Unregister を実行する必要があります。デバッグビルドでは、別のモジュールからプロバイダーハンドルを使用して書き込もうとすると、アサーションが起動します。

プロバイダー名と ID

ETW は、プロバイダー ID (プロバイダー GUID またはコントロール GUID とも呼ばれます) を使用して、イベントのフィルター処理とルーティングを実行します。たとえば、プロバイダー ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} を持つという名前MyCompany.MyComponentのプロバイダーがある場合は、のような tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5tracelog コマンドを使用して、このプロバイダーからイベントをキャプチャするトレースを開始できます。

すべての ETW プロバイダーは、プロバイダー名とプロバイダー ID の両方で識別されます。他のプロバイダーと競合しないように、名前と ID の両方が一意である必要があります。さらに、名前と ID をリンクする必要があります。ETW プロバイダーの特定の ID で特定の名前を使用すると、その名前は他の ID と共に使用しないでください。その ID は他の名前と共に使用しないでください。

プロバイダー ID には、SDK ツールまたは https://uuidgen.orgを使用して生成される任意の一意の guidgen GUID を指定できます。ただし、プロバイダー ID にランダムに生成された GUID を使用する代わりに、以下で説明する ETW 名ハッシュアルゴリズムを使用してプロバイダー名からプロバイダー ID を生成することをお勧めします。これにはいくつかの利点があります。名前だけを覚える方が簡単です。ID と名前は自動的にリンクされます。tracelog、traceview、EventSource、WPR などのツールでは、このアルゴリズムを使用して生成された ID を使用するプロバイダーが特別にサポートされています。

たとえば、プロバイダー ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} を持つという名前MyCompany.MyComponentのプロバイダーがある場合は、のような tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponenttracelog コマンドを使用して、このプロバイダーからイベントをキャプチャするトレースを開始できます。これは、プロバイダー名 MyCompany.MyComponentをハッシュすることによってプロバイダー ID が{ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}生成されたために機能するため、tracefmt ツールはと同等であると見-guid *MyCompany.MyComponentな-guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5されます。

PowerShell を使用すると、 EventSource クラスを介して ETW 名ハッシュアルゴリズムを使用して、特定のプロバイダー名のプロバイダー ID を取得できます。

[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid

結果:

Guid
----
ce5fa4ea-ab00-5402-8b76-9f76ac858fb5

C# では、ETW 名ハッシュアルゴリズムを次のように実装できます。

static Guid ProviderIdFromName(string name)
{
    var signature = new byte[] {
        0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8,
        0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB };
    var nameBytes = System.Text.Encoding.BigEndianUnicode.GetBytes(name.ToUpperInvariant());
    using (var sha1 = new System.Security.Cryptography.SHA1Managed())
    {
        sha1.TransformBlock(signature, 0, signature.Length, null, 0);
        sha1.TransformFinalBlock(nameBytes, 0, nameBytes.Length);
        var hash = sha1.Hash;
        Array.Resize(ref hash, 16);
        hash[7] = (byte)((hash[7] & 0x0F) | 0x50);
        return new Guid(hash);
    }
}

例

#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
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

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

こちらもご覧ください

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER マクロ (traceloggingprovider.h)

構文

パラメーター

戻り値

解説

プロバイダー名と ID

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース