はじめに
今回の記事は WPP ログの確認方法についてです。
デバイスドライバ開発では、動作検証やエラー解析などで WPP ログを確認することがあります。そのときに使用するツールと、使用方法についてまとめていきます。
使用するツールは TraceView、Tracepdb、Tracefmt の 3 つです。
これらは WDK (Windows Driver Kit) に含まれているツールです。この記事の手順を試す場合は、あらかじめ WDK をインストールしておいてください。
これらのツールを使うことで、以下の2つのことができます。
- TraceView でリアルタイムにログを確認する
- ETL を保存して、あとから Tracepdb と Tracefmt で読める形にする
それでは、WPP ログを確認する最短運用を整理していきます。
この記事で扱う範囲
本記事で扱うのは、次の流れです。
- TraceView でプロバイダを指定してセッションを開始する
- サンプルアプリを動かしてリアルタイムログを確認する
- 必要なら同じ流れで ETL も保存する
- Tracepdb で PDB から TMF を生成する
- Tracefmt で ETL を整形して確認する
本記事は WPP ログの確認と ETL の取得、整形に焦点を絞っているため、TraceView の全機能や Tracefmt の細かいオプション、その他の ETL 取得方法については今回は書いていません。
他の機能については記事の最後に参考文献を添付するので、興味がある方はそちらも読んでみてください。
先に全体像
最初に全体の流れを説明しておきます。
リアルタイムで確認したい場合
TraceView でセッション開始
↓
サンプルアプリを動かす
↓
TraceView でリアルタイムログを見る
ETL を保存してあとから読みたい場合
TraceView でセッション開始し、ETL も保存する
↓
サンプルアプリを動かす
↓
セッション停止後、ETL を取得する
↓
Tracepdb で PDB から TMF を生成する
↓
Tracefmt で ETL を整形する
各ツールの役割は以下のようになります。
| ツール | この記事での役割 |
|---|---|
| TraceView | セッション開始とリアルタイム確認、必要なら ETL 保存 |
| Tracepdb | PDB から TMF を生成する準備ツール |
| Tracefmt | ETL を人が読める文字列へ整形するツール |
最低限押さえたい用語
WPP ログの確認や整形で使用するファイルについて説明しておきます。
今回使用するのは次の 3 つです。
ETL があればすぐに読めそうに見えますが、WPP ログでは PDB や TMF が必要になることがあります。それぞれの役割について押さえておきましょう。
ETL
トレースログの保存先になるファイルです。
PDB
デバッグシンボルのファイルです。WPP ログを読める形にする情報も、ここから参照または抽出します。
TMF
WPP ログを整形するためのファイルです。今回は Tracepdb を使って PDB から生成します。
今回使うサンプル
動作確認には WPP トレース付きコンソールアプリ "WppTraceConsole" を使います。
コマンドを打つと返答を返す簡単な機能のアプリで、後続の手順ではこのアプリに対応する PDB を使用します。
↓はアプリを動かしたときの表示画面です。
WPPログの確認、整形手順
1. TraceView でセッションを開始する
まずは TraceView で対象プロバイダのトレースセッションを開始します。
今回はサンプルアプリの PDB ファイルを使用してログを確認します。
TraceView を起動したら以下の手順で PDB ファイルを設定します。
[File] → [New Log Session...] → [PDB (Debug Information) File]を選択
→ サンプルアプリの PDB ファイルを参照
PDB 参照後は、[OK]→[次へ]→[完了]でトレースセッションを開始します。今回は他の値は既定値のまま進めています。
2. サンプルアプリを動かしてリアルタイムログを確認する
TraceView のセッションを開始したら、サンプルアプリを起動してコマンドを打ちます。
今回は以下の順でコマンドを打ち込んでみます。
info
warn
error
これで TraceView 側にリアルタイムでログが流れてくれば、まずは取得側が動いていることを確認できます。
↓はコマンド打ち込み後に TraceView に表示された WPP ログです。
この段階では、以下の点が確認できれば十分です。
- セッションが正しく開始できているか
- 対象プロバイダからイベントが出ているか
- コマンドに応じてログが増えるか
3. 必要なら同じセッションで ETL も保存する
リアルタイム確認だけで済むなら、前項までで終わりです。
一方で、あとからログを見返したい場合や、他の人に渡したい場合は ETL も保存しておくと便利です。
今回は、TraceView でトレースセッションを開始するときに一緒に ETL を取得する方法を説明します。
PDB を参照するまでは同様の操作なので省略します。
PDB 参照後、[OK] → [次へ]をクリックすると以下のダイアログが表示されるので、[Log Trace Event Data To File]にチェックを付けて[完了]をクリックします。
これで ETL が保存されます。（このとき ETL には任意の名前を付けることも可能です）
ETL は、この画面で指定した保存先に出力されます。今回の例では TraceView 側で設定した保存先に ETL を出力しています。
4. Tracepdb で PDB から TMF を生成する
ETL を取得したら、次は Tracepdb で PDB から TMF を生成します。
tracepdb を cmd で起動し、以下のコマンドを実行します。
tracepdb.exe -f .\WppTraceConsole.pdb -p .\tmf
意味は次の通りです。
- -f: 入力に使う PDB を指定する
- -p: 生成した TMF の出力先ディレクトリを指定する
実行後、指定したディレクトリに GUID 名の TMF ファイルが生成されます。
※TMF を生成するときは、ETL を取得したときの実行ファイルに対応する PDB を使ってください。ビルドし直した別バージョンの PDB を使うと、うまく整形できないことがあります。
5. Tracefmt で ETL を整形して確認する
TMF が用意できたら、Tracefmt で ETL を整形します。
tracefmt を cmd で起動し、以下のコマンドを実行します。
tracefmt.exe .\trace.etl -p .\tmf -o .\trace.txt
ここでは、取得した ETL を trace.etl という名前で保存した例を使っています。別名で保存した場合は、そのファイル名に読み替えてください。
意味は次の通りです。
- .\trace.etl: 整形したい ETL
- -p .\tmf: TMF を置いたディレクトリ
- -o .\trace.txt: 整形結果の出力先
これで、ETL の中身を人が読める形で確認できます。
↓は実際に整形した ETL の中身です。
ツール操作がうまくいかないとき
ログの取得や読み取りで問題が起きた場合は以下のように切り分けてみましょう。
- TraceView に何も出ない場合は、セッション設定やプロバイダ指定、アプリ側の出力を疑う
- ETL は取れているのに Tracefmt で読めない場合は、PDB や TMF の対応関係を疑う
- リアルタイムでは見えているのに保存結果の確認で詰まる場合は、TraceView 側の保存設定を疑う
注意点
- Tracepdb と Tracefmt を使う場合は、ETL を取得したときの PDB と対応していることが重要です。ここがずれると、整形結果が崩れたり、必要な文字列が出なかったりします
- TraceView の画面名や設定項目名は、バージョンや環境によって多少見え方が異なることがあります
まとめ
今回の記事で扱った流れは、以下の通りです。
- TraceView でセッション開始
- サンプルアプリを動かしてリアルタイムログ確認
- 必要なら同じセッションで ETL 保存
- Tracepdb で PDB から TMF 生成
- Tracefmt で ETL を整形
ここまでで TraceView、Tracepdb、Tracefmt を使用して WPP ログの確認と ETL の整形手順をまとめました。
はじめて触るときは難しく感じるかもしれませんが、上記の流れさえ押さえておけば、リアルタイム確認と後追い解析の両方に対応できます。
デバイスドライバの開発では WPP ログの確認は頻繁に行うので、ぜひ今回紹介した方法も試してみてください！