TraceLoggingChannel マクロ (traceloggingprovider.h)

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

ほとんどの 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

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

次の方法で共有

TraceLoggingChannel マクロ (traceloggingprovider.h)

構文

パラメーター

戻り値

解説

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

要件

こちらもご覧ください

フィードバック

その他のリソース

次の方法で共有

TraceLoggingChannel マクロ (traceloggingprovider.h)

構文

パラメーター

戻り値

解説

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

要件

こちらもご覧ください

フィードバック

その他のリソース

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