次の方法で共有

トレース ログ C/C++ クイック スタート

  • [アーティクル]

次のセクションでは、トレース ログを C/C++ ユーザー モード コードに追加するために必要な基本的な手順について説明します。

前提条件

  • Microsoft Visual Studio 2013 以降
  • Windows 10 ソフトウェア開発キット (SDK) は、ユーザー モード プロバイダーを作成するために必要です。
  • カーネル モード プロバイダーを作成するには、Windows 10用 Windows Driver Kit (WDK) が必要です。

重要

未解決 EventRegisterの、、 EventWriteTransferまたは EventUnregister 関数のリンカー エラーを回避するには、これらの例をコンパイルするときに と advapi32.lib リンクします。

これらの例のイベントを収集してデコードするには、tracelog や traceview などのツールを使用してトレースを開始し、例を実行し、tracelog や traceview などのツールを使用してトレースを停止し、tracefmt や traceview などのデコード ツールを使用してトレースをデコードする必要があります。 たとえば、プロバイダーが GUID を {0205c616-cf97-5c11-9756-56a2cee02ca7}使用して定義されている場合、Windows SDK ツール のトレースログ と tracefmt を使用して、これらの例のイベントを次のように表示できます。

  • tracelog -start MyTraceSession -f MyTraceFile.etl -guid #0205c616-cf97-5c11-9756-56a2cee02ca7
  • 例を実行します。
  • tracelog -stop MyTraceSession
  • tracefmt -o MyTraceFile.txt MyTraceFile.etl
  • notepad MyTraceFile.txt

SimpleTraceLoggingExample.h

この例のヘッダーには TraceLogging API が含まれており、forward はイベントのログ記録に使用されるプロバイダー ハンドルを宣言します。 TraceLogging を使用するクラスには、このヘッダーが含まれるので、ログ記録を開始できます。

#pragma once

#include <windows.h> // Definitions required by TraceLoggingProvider.h
#include <TraceLoggingProvider.h> // The C/C++ TraceLogging API

// Forward-declare the g_hMyComponentProvider variable that you will use for tracing in this component
TRACELOGGING_DECLARE_PROVIDER(g_hMyComponentProvider);

ヘッダー ファイルには、C/C++ TraceLogging API を定義する が含まれています TraceLoggingProvider.h 。 によって使用されるTraceLoggingProvider.h定数を定義するため、最初に を含めるwindows.h必要があります。

ヘッダー ファイル転送は、トレース ログ API に渡してイベントをログに記録するプロバイダー ハンドル g_hMyComponentProvider を宣言します。 このハンドルには、トレース ログを使用するすべてのコードからアクセスできる必要があります。

TRACELOGGING_DECLARE_PROVIDER は、指定した名前を extern const TraceLoggingHProvider 使用してハンドルを作成するマクロです。上記の例では です g_hMyComponentProvider。 実際のプロバイダー ハンドル変数をコード ファイルに割り当てます。

SimpleTraceLoggingExample.cpp

次の例では、プロバイダーを登録し、イベントをログに記録し、プロバイダーの登録を解除します。

#include "SimpleTraceLoggingExample.h"

// Define a handle to a TraceLogging provider
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{

    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

    // Stop TraceLogging and unregister the provider
    TraceLoggingUnregister(g_hMyComponentProvider);
}

上記の例には SimpleTraceLoggingExample.h が含まれています。これには、コードでイベントをログに記録するために使用するグローバル プロバイダー変数が含まれています。

TRACELOGGING_DEFINE_PROVIDER マクロはストレージを割り当て、プロバイダー ハンドル変数を定義します。 このマクロに指定する変数名は、ヘッダー ファイルの TRACELOGGING_DECLARE_PROVIDER マクロで使用した名前と一致している必要があります。

プロバイダー ハンドルを登録する

プロバイダー ハンドルを使用してイベントをログに記録するには、 まず TraceLoggingRegister を呼び出してプロバイダー ハンドルを登録する必要があります。 これは通常、メイン() または DLLMain() で行われますが、イベントのログ記録を試みる前であれば、いつでも実行できます。 プロバイダー ハンドルを登録する前にイベントをログに記録すると、エラーは発生しませんが、イベントはログに記録されません。 上記の例の次のコードは、プロバイダー ハンドルを登録します。

// Define the GUID to use in TraceLoggingProviderRegister
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{
    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

トレース ログ イベントをログに記録する

プロバイダーが登録されると、次のコードは単純なイベントをログに記録します。

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

TraceLoggingWrite マクロは、最大 99 個の引数を受け入れます。 イベント名は UTF-8 形式で格納されます。 イベント名またはフィールド名に '\0' 埋め込み文字を使用しないでください。 許可される文字には他の制限はありませんが、一部のイベント デコーダーまたはイベント プロセッサには独自の制限がある場合があります。

イベント名に続く各引数は、 トレース ログ ラッパー マクロ内でラップする必要があります。 C++ を使用している場合は、ラッパー マクロを TraceLoggingValue 使用して、引数の型を自動的に推測できます。 C で記述する場合、またはフィールド型をより細かく制御する場合は、、TraceLoggingUnicodeStringTraceLoggingStringなどのTraceLoggingInt32型固有のフィールド マクロを使用する必要があります。

1 つのイベントのログ記録に加えて、TraceLoggingWriteActivity または TraceLoggingWriteStart/TraceLoggingWriteStop マクロ (TraceLoggingActivity.h) を使用して、アクティビティ別にイベントをグループ化することもできます。 アクティビティはイベントを関連付け、開始と終了を持つシナリオに役立ちます。 たとえば、アクティビティを使用して、アプリケーションの起動から始まり、スプラッシュスクリーンが使用可能になるまでの時間を含み、アプリケーションの最初の画面が表示されたときに終了するシナリオを測定できます。

アクティビティは、1 つのイベントをキャプチャし、そのアクティビティの開始と終了の間に発生する他のアクティビティを入れ子にします。 アクティビティにはプロセスごとのスコープがあり、マルチスレッド イベントを適切に入れ子にするには、スレッド間で渡す必要があります。

プロバイダー ハンドルのスコープは、それが定義されているモジュール (DLL、EXE、または SYS ファイル) に制限されます。 ハンドルを他の DLL に渡さないでください。 B.DLLで定義されているプロバイダー ハンドルを使用して、A.DLLで TraceLoggingWrite マクロが呼び出されると、問題が発生する可能性があります。 この要件を満たす最も安全で最も効率的な方法は、常にグローバル プロバイダー ハンドルを直接参照し、プロバイダー ハンドルをパラメーターとして渡さないことを意味します。

プロバイダーの登録を解除する

コンポーネントをアンロードする前に、TraceLogging プロバイダーの登録を解除する必要があります。 これは、DLL とドライバーにとって特に重要です。 DLL またはドライバーがプロバイダーの登録を解除せずにアンロードすると、クラッシュが発生する可能性があります。

次のコードは、プロバイダーの登録を解除します。

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hMyComponentProvider);

互換性

TraceLoggingProvider.h は、その構成に応じて下位互換性がある場合があります (結果のプログラムは Windows Vista 以降で実行されます)、または新しい OS バージョン用に最適化できます。 TraceLoggingProvider.h では、WINVER (ユーザー モード) とNTDDI_VERSION (カーネル モード) を使用して、以前の OS バージョンと互換性があるか、新しい OS バージョン用に最適化する必要があるかを判断します。

ユーザー モードの場合、WINVER を設定する前に を含める <windows.h> 場合は、 <windows.h> WINVER を SDK の既定のターゲット OS バージョンに設定します。 WINVER が 0x602 以上に設定されている場合、 TraceLoggingProvider.h Windows 8 以降の動作が最適化され、アプリは以前のバージョンの Windows では実行されません。 Vista または Windows 7 でプログラムを実行する必要がある場合は、 を含める <windows.h>前に、WINVER を適切な値に設定してください。

同様に、NTDDI_VERSIONを設定する前に を含める <wdm.h> 場合は、 <wdm.h> NTDDI_VERSIONを既定値に設定します。 NTDDI_VERSIONが 0x06040000 以上に設定されている場合、TraceLoggingProvider.h はWindows 10の動作を最適化し、以前のバージョンの Windows ではドライバーが動作しません。

この動作は、 を含むTraceLoggingProvider.h前に を設定TLG_HAVE_EVENT_SET_INFORMATIONすることで方向を制御できます。 マクロの詳細については、ヘッダーの TraceLoggingProvider.h コメントを TLG_HAVE_EVENT_SET_INFORMATION 参照してください。

まとめと次のステップ

Windows パフォーマンス ツール (WPT) を使用してトレース ログ データをキャプチャおよび表示する方法については、「 トレース ログ イベントの記録と表示」を参照してください。

その他の C++ トレース ログの例については、「C/C++ トレース ログの例」を参照してください。