Windows ソフトウェア トレース プリプロセッサ

Windowsソフトウェア トレース プリプロセッサ( WPP、プリプロセッサと関連サポート ツールはWPP ソフトウェア トレースと呼ばれます) は、WMIイベント トレースの使用を簡素化し、 Windows 2000以降のオペレーティング システムを対象とするドライバーとアプリケーションで効率的なソフトウェア トレースを実装するプリプロセッサです。WPP はMicrosoftによって作成され、 Windows DDKに含まれています。WPP は適用範囲が広いですが、Windows SDKには含まれていないため、主に Windows DDK を購入するソフトウェア ベンダーが作成したドライバーとドライバー サポート ソフトウェアに使用されます。

ソフトウェア トレースは、プログラムの実行に関する情報を記録するためのログ記録の特殊な使用法です。この情報は、一般的にデバッグに使用されます。イベント ログ記録の主な目的は、システム管理者が監査できる (イベント ビューアーなどを参照) か、管理ツールで分析できるイベントの記録を作成することですが、ソフトウェア トレースは主にソフトウェア開発者のデバッグ支援機能です。そのため、ローカライズ可能性や標準ベースの出力形式など、イベント ログ記録の非機能要件の多くは、ソフトウェア トレースのほとんどの用途では明示的に非目標となっています。一方、ソフトウェア トレースには、イベント ログ記録では一般にそれほど重要ではない、パフォーマンスに関する特別な要件があります。たとえば、ソフトウェア トレースの一般的な使用法の 1 つであるin/out トレースでは、関数またはメソッドのエントリ ポイントと戻り値で出力が生成されるため、開発者はデバッガーまたはテキストベースのログ ファイルで、多くの場合パラメーターと戻り値を含む実行パスを視覚的に追跡できます (これは、シーケンス図の実行時版と見なすことができます)。このタイプのトレースは開発者にとっては便利ですが、無効にできない場合（条件付きコンパイルによるコンパイル時、またはフラグによる実行時のいずれか）は、ソフトウェア製品のパフォーマンスに大きな悪影響を与える可能性があります。

ソフトウェア トレースに特有の追加の考慮事項は次のとおりです。

• プロプライエタリソフトウェアでは、トレースデータに製品のソースコードに関する機密情報が含まれる場合があります。
• 実行時にトレースを有効または無効にする場合、多くのトレース方法ではバイナリに大量の追加データを含める必要があり、トレースが無効になっている場合でも間接的にパフォーマンスが低下する可能性があります。
• コンパイル時にトレースが有効または無効になっている場合、顧客のマシン上の問題のトレース データを取得できるかどうかは、顧客がトレースが有効になっている特別なバージョンのソフトウェアをインストールする意思と能力があるかどうかによって決まります。
• ドライバーなどの特定の種類のソフトウェアでは、トレースが有効になっている場合でも、厳しいパフォーマンス要件を満たす必要があります。

最初の 2 つの考慮事項により、従来のソフトウェア トレース方法では、条件付きコンパイルを使用して、コンパイル時にトレース (およびトレース データの組み込み) を有効または無効にします。たとえば、C プリプロセッサを使用する場合、次のようにマクロを定義できますDebugOut。

#ifdef _DEBUG
#define DebugOut(msg, ...) \
    DebugPrintf(__FUNCTION__ "(" __FILE__ ":" TO_STRING(__LINE__) ")\t" \
        メッセージ、__VAR_ARGS__)
＃それ以外
#define DebugOut(msg, ...)
#終了

ここで、 は行TO_STRING番号 ( __LINE__) を文字列に変換するマクロであり、たとえばデバッガーにテキストを出力する printfDebugPrintfのような関数です。

次に、次のコードを実行します。

DebugOut("エラー %d が発生しました\n", error_code);

デバッグ ビルドの場合のみ、次のような出力が生成されます。

SomeFunction(file.c:78) エラー 217 が発生しました

特定の種類のトレース (特に in/out トレース) 用の別の手法として、インストルメンテーションを使用する方法があります。この手法は多くの主要な問題に対処できますが、常に使用できるわけではありません (通常はマネージ コードでのみ使用できます)。

WMI イベント トレースは、特にドライバーなどのパフォーマンスが重要なコードでのトレースのパフォーマンスに対処するテクノロジの例です。また、開発者が人間が判読できるトレース データ ("Error %d occurred\n"上記の例) をコードとは別に定義して製品に組み込まれないようにすることで (コードでは、特定のメッセージがメッセージ番号で参照されます)、機密トレース情報の配布を制御するという懸念にも対処できます。ただし、いくつかの重要な制限があります。

• WMI イベント トレースは、それ自体では"SomeFunction(file.c:78)"トレース メッセージの一部を自動的に生成することはできません。これは、WMI イベント トレースに固有のものではなく、このようなテクノロジすべてに共通する制限です。
• トレース データの人間が読める部分をコードから分離する必要があると、コードの可読性が低下する可能性があります。
• この手法を使用すると、「ワンショット」トレース メッセージに大幅な開発オーバーヘッドが発生する可能性があります。

WPP はコンパイル前 (つまり、C プリプロセッサよりも前) に実行され、処理するファイルごとにトレース メッセージ ヘッダーfilename.tmhを生成します (デフォルトではこのヘッダーはで、 はfilename処理されるソース ファイルの名前です)。このヘッダーは、次のように明示的にソース ファイルに含める必要があります。

// ファイル: file.cxx
// このファイルはWPPの使用例です
#include "ファイル.tmh"

WPP のC / C++構文の理解は非常に限られています。特に、マクロを展開したり(必要な特別な状況を除く)、プラグマを処理したり、セマンティック分析を実行したりすることはありません。

開発者は、構成ファイル、コメント内の特別な注釈、コマンド ライン パラメータ、またはこれらの方法の組み合わせを介して、WPP が処理する 1 つ以上のトレース マクロを指定します。WPP は、処理するマクロの 1 つを検出するたびに、トレース メッセージ マクロを生成します。つまり、たとえば がDoTraceトレース マクロである場合、WPP は の発生ごとに個別のマクロを生成しますDoTrace。生成されたトレース メッセージ マクロは、ファイル名と行番号によって区別され、さまざまなプリプロセッサ トリックを使用して、WPP は元のトレース マクロを定義し、発生ごとに適切なトレース メッセージ マクロを展開します。

WPP によるトレース メッセージ マクロの生成方法は、テンプレート ファイルによって異なります (ファイルの形式は文書化されていません)。WPP に含まれる既定のテンプレート ファイルでは、トレース メッセージの文字列を注釈に含めるように指定しています(Microsoft コンパイラの __annotation 機能を使用)。これらの文字列はコンパイルされたコードには含まれませんが、WPP に含まれるツールが理解できる形式でデバッガー シンボル ファイルに含まれます。トレース メッセージ マクロには、フラグを使用してトレースを有効または無効にするロジックと、WMI イベント トレース API の呼び出しも含まれます。

• WPP はマクロを展開しないため、別のマクロの定義に含まれるトレース マクロのインスタンス化は認識されません。たとえば、 がDoTraceトレース マクロで、マクロがCheckForErrors次のように定義されている場合、

#CheckForErrors(エラーコード) を定義します \
    if (IsError(エラーコード)) \
    {\
        DoTrace("エラー %d が発生しました\n", err); \
        エラー処理(エラーコード); \
    }

DoTraceWPP は、発生場所のトレース メッセージ マクロを生成しませんCheckForErrors。WPP はこの問題に対してアドホックな回避策を提供していますが、回避策を使用しても表現できないマクロの小さなクラスがまだ存在します。

• 既定のテンプレート ファイルは、Microsoft コンパイラでのみ適切に動作するコードを生成します。これはプリプロセッサ固有の制限ではありませんが、テンプレート ファイル (トレース メッセージ ヘッダーで生成されるコードを制御) が文書化されていない形式を使用しているため、実際には WPP は Microsoft コンパイラでのみ適切に動作します。
• 以前のバージョンの WPP では、ソース ファイルに複数のトレース マクロ ヘッダーが含まれている場合 (たとえば、トレースを含むソース ファイルに、インライン関数でトレースを含むヘッダーが含まれている場合) にコンパイル エラーが発生しました。これは最新バージョンで修正されています。これはテンプレート ファイルの制限であり、WPP ツール自体の制限ではないことに注意してください。
• トレース メッセージ マクロはファイルと行番号によって区別されるため、ソース コード内の行ごとにトレース マクロは 1 つしか存在できません。

• MSDN の WPP ソフトウェア トレース リファレンス