TraceLoggingChannel マクロ (traceloggingprovider.h)

  • [アーティクル]

イベントのチャネルを設定するトレース ログ ラッパー マクロ。

ほとんどの TraceLogging イベントは、イベントの既定のチャネルを変更する必要はありません。また、TraceLoggingChannel を使用しないでください。

構文

void TraceLoggingChannel(
  [in]  eventChannel
);

パラメーター

[in] eventChannel

イベントをログに記録するチャネル。 これは、0 ~ 255 の整数値です。

イベント チャネルの詳細については、「 EVENT_DESCRIPTOR 」を参照してください。

戻り値

なし

解説

TraceLoggingChannel(eventChannel)は、TraceLoggingWrite マクロの呼び出しのパラメーターとして使用できます。 ほとんどの TraceLogging イベントは、イベントの既定のチャネルを変更する必要はありません。また、 TraceLoggingChannel を使用しないでください。

eventChannel パラメーターは、コンパイル時定数 0 から 255 である必要があります。 arg が指定されていない TraceLoggingChannel(n) 場合、既定のチャネルは 11 (WINEVENT_CHANNEL_TRACELOGGING) であり、これが通常の TraceLogging イベントであることを示します。 複数 TraceLoggingChannel(n) の引数が指定されている場合は、最後 TraceLoggingChannel(n) のパラメーターの値が使用されます。

チャネルは、高度な Windows イベント トレーシング (ETW) シナリオで使用されます。 これには、 Windows イベント ログなどのシステム定義イベント コンシューマーへの書き込みが含まれます。

警告

プロバイダーがWindows 10より前の Windows で実行される場合は、TraceLoggingChannel を使用しないでください。 イベント をイベント デコーダーによって TraceLogging 互換として認識するには、チャネルが既定値 (11) に設定されているか、EventWrite 中に ETW ランタイムによって TraceLogging イベントとしてマークされている必要があります。 このイベント マーキングは、EventSetInformation を呼び出してプロバイダーをトレース ログ プロバイダーとして構成することで有効になります。 Windows 10 以降の EventSetInformation では、チャネルに関係なく TraceLogging イベントをサポートできますが、以前のバージョンの Windows では、トレース ログ イベントのマーキングをサポートする前に Windows 更新プログラムが必要です。 EventSetInformation が更新されていないシステムでキャプチャされたイベントの場合、TraceLogging イベントを認識する唯一の方法はチャネル 11 であるため、他のチャネルを含むイベントが正しくデコードされない可能性があります。

トレース ログとイベント ログ

ほとんどの場合、開発者は、イベント ログで記録する必要があるイベントにマニフェスト ベースの ETW を使用します。 イベント ログは、主に、システムの管理者に役立つ可能性が高い少量のイベントを収集することを目的としています。 マニフェストベースの ETW は、慎重にキュレーションされたイベント (コンポーネントのすべてのイベントが 1 つのマニフェスト ファイルで記述されています) をサポートし、管理者がイベントに対応する方法を知るのに役立つローカライズ可能なメッセージ文字列をサポートするため、これに適しています。

TraceLogging イベントにはメッセージ文字列がないため、一般的には一元的にキュレーションされませんが、一部のイベント ログ シナリオではトレース ログが適切な場合があります。 たとえば、Windows ログ (アプリケーション、セキュリティ、セットアップ、システム) に移動するイベントは常にローカライズされたメッセージ文字列を持つ必要があり、システム管理者にとって常に役立つはずですが、アプリケーションとサービス ログに記録されるイベントはより技術的であり、診断情報を記録できます。 アプリケーションおよびサービス ログに書き込む場合は、トレース ログを使用して、ログに記録されたイベントの管理を簡略化できます。

Windows イベント ログでのトレース ログ イベントの使用は、イベント ログでの通常のマニフェスト ベースのイベントの使用と似ています。 プロバイダーとチャネルを定義するためにマニフェストを作成して登録する必要はありますが、マニフェストで個々のイベントを定義する必要はありません。

  • プロバイダーとイベント ログ チャネルを定義する ETW マニフェストを記述します。 マニフェストのプロバイダーは、 TRACELOGGING_DEFINE_PROVIDER マクロで使用したのと同じプロバイダー名とプロバイダー GUID (プロバイダー ID) を使用する必要があります。 TraceLogging イベントは自己記述型であるため、マニフェストに または <template> 定義を含める<event>必要はありません。
  • コンポーネントのビルド プロセスで、Windows SDK 10.0.22621 以降のメッセージ コンパイラ (MC.exe) を使用してマニフェストをコンパイルします。 これにより、次のファイルが生成されます。
    • ManifestName.h: 定数定義を含む C/C++ ヘッダー。 これにより、TraceLogging イベントで使用する必要がある ChannelSymbol 定数と ChannelSymbol_KEYWORD 定数が定義されます。 (定数の実際の名前は、チャネルごとに異なります)。
    • ManifestName.rc: マニフェスト BIN データをバイナリ (EXE、DLL、または SYS) ファイルに追加する リソース コンパイラ (RC.exe ) スクリプト。 このリソース スクリプトは、コンポーネント内のいずれかのバイナリ ファイルのリソースに含める必要があります。
    • ManifestNameTEMP.BIN、 MSG00001.bin: によって ManifestName.rc参照されるマニフェスト BIN データ。
  • #include 生成された ManifestName.h ファイルを、TraceLogging イベントを生成する必要があるコードに格納されます。 これにより、 ChannelSymbol および ChannelSymbol_KEYWORD 定数が定義されます。
    • マニフェストの または <importChannel> 定義にシンボル属性を<channel>指定した場合、ChannelSymbol の名前はシンボル属性の値になります。 それ以外の場合、ChannelSymbol はProviderSymbol_CHANNEL_ChannelNameされます (つまり、要素の<provider>シンボルと、 または <importChannel> 要素の名前を<channel>使用します)。
    • ChannelSymbol_KEYWORDの名前は、ChannelSymbol の後に 続_KEYWORDく という名前です。
    • ChannelSymbol_KEYWORD定数は、10.0.22621 以降によってのみ生成されますMC.exe。
  • イベント ログに移動する各 TraceLogging イベントは、次を使用する必要がありますTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)を使用して、イベントのチャネルとキーワード (keyword)を設定します。 たとえば、チャネルのシンボルが の場合、MY_CHANNELイベントのマクロにTraceLoggingWriteパラメーターとして を追加TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD)します。
  • イベント ログでプロバイダーを認識するには、マニフェストの情報を、ターゲット システムにインストールされるモジュール (DLL、EXE、または SYS ファイル) の リソースに含める必要があります 。
  • イベント ログがプロバイダーからイベントを受信するには、コンポーネントのインストール時に を使用してwevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll、マニフェストをターゲット システムに登録する必要があります。 コンポーネントのアンインストール中に を使用して wevtutil um ManifestFile.man マニフェストの登録を解除する必要もあります。

重要

プロバイダーがイベント ログに登録されている場合、イベントがイベント ログを対象としていない場合でも、プロバイダーによって生成されるすべてのイベントに、TraceLoggingKeyword で指定された 0 以外のキーワード (keyword)が必要です。 キーワード (keyword) 0 のイベントは効率的にフィルター処理できず、破棄されるためだけにイベント ログに配信されます。 イベント ログがプロバイダーからのイベントをリッスンしている場合、キーワード 0 のイベントは、イベント ログのオーバーヘッドを不必要に増加させます。

イベント ログの TraceLogging イベントの例:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

必要に応じて、複数の TraceLoggingKeyword 引数を使用するか、または 1 つの TraceLoggingKeyword 引数に複数のキーワードを指定することによって、必要に応じて、追加のユーザー指定キーワードをイベントに追加できます 。例: 。 TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD)

要件

要件 値
サポートされている最小のクライアント Windows 10 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2012 R2
対象プラットフォーム Windows
ヘッダー traceloggingprovider.h

こちらもご覧ください

EVENT_DESCRIPTOR

TraceLoggingWrite

トレース ログ ラッパー マクロ