Logman を使用して USB イベント トレースをキャプチャする方法

  • [アーティクル]

この記事では、Logman ツールを使用して USB ETW イベント トレースをキャプチャする方法について説明します。 Logman は、Windows に組み込まれているトレース ツールです。 Logman を使用して、イベントをイベント トレース ログ ファイルにキャプチャできます。

前提条件

イベント トレース ログ ファイルは非常に迅速に拡張できますが、小さいログ ファイルは移動しやすく、送信も簡単です。 トレースを開始する前に、次の手順を実行して無関係なイベントをログから除外し、調べたいデバイスのアクティビティに集中できるようにすることを検討してください。

  • 重要でない USB デバイスのうち、目的のデバイスではないデバイスを切断します。 デバイスの数が少ないほど、トレースが小さくなり、読みやすく、分析しやすくなります。
  • システムに USB キーボードまたはマウスがある場合は、代わりにリモート デスクトップを使用してトレース コマンドを入力します。
  • 対象の操作の周囲でトレースの開始点と終了点をできるだけ狭くします。
  • 特定のカテゴリの USB イベントのみに関心がある場合は、キーワードを使用して、記録されるイベントをフィルター処理できます。 詳細については、「解説」を参照してください。

USB 3.0 ドライバー スタックからのイベント トレースは、Windows 7 で導入された USB 2.0 ドライバー スタック トレースに似ています。 USB 2.0 ドライバー スタックからのイベント トレースは、Windows 8 コンピューターでキャプチャできます。 USB 2.0 および USB 3.0 ドライバー スタックからイベント トレースをキャプチャする方法も同様です。 USB 2.0 または USB 3.0 ドライバー スタックからイベントを個別にキャプチャできます。 USB 2.0 デバイスを USB 3.0 ホスト コントローラーに接続すると、USB 3.0 ドライバー スタックからイベント トレースが取得されます。 その場合、USB 2.0 デバイスの新しい USB 3.0 ドライバー スタック イベントを表示します。

手順

USB トレース イベントを収集するには

  1. 管理者特権があるコマンド プロンプト ウィンドウを開きます。 これを行うには、[スタート] を選択し、検索ボックスに「cmd」と入力し、cmd.exeを長押し (または右クリック) して、[管理者として実行] を選択します。

  2. コマンド プロンプト ウィンドウで、次のコマンドを入力してキャプチャ セッションを開始します。

    logman create trace -n usbtrace -o %SystemRoot%\Tracing\usbtrace.etl -nb 128 640 -bs 128
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBXHCI (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3 (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBPORT
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB
logman update trace -n usbtrace -p Microsoft-Windows-Kernel-IoTrace 0 2
logman start -n usbtrace

    これらの各コマンドが完了すると、Logman は The command completed successfully. を表示します

  3. キャプチャの操作を実行します。 たとえば、デバイス列挙のイベントをキャプチャするには、デバイス マネージャーで「不明なデバイス」として表示される USB フラッシュ ドライブを接続できます。 コマンド プロンプト ウィンドウは開いたままにします。

  4. シナリオが完了したら、セッションを停止します。 キャプチャ セッションを終了するには、次のコマンドを入力します。

    USB ハブとポート イベントの収集は、次のコマンドを実行して停止できます。

    logman stop -n usbtrace
logman delete -n usbtrace
move /Y %SystemRoot%\Tracing\usbtrace_000001.etl %SystemRoot%\Tracing\usbtrace.etl

上記のキャプチャ セッションでは、usbtrace.etl という名前の etl ファイルが生成されます。 トレース ファイルは %SystemRoot%\Tracing\usbtrace.etl (C:\Windows\Tracing\usbtrace.etl) に格納されます。 次のセッションをキャプチャするときに上書きされないように、ファイルを別の場所に移動するか、名前を変更します。

このファイルには、USB 3.0 および USB 2.0 ドライバー スタックからのイベント トレースが含まれています。 イベント トレースを 1 つの USB ドライバー スタックのみに減らす場合は、次のトレース セッションからもう一方のドライバー スタックを削除します。 これを行うには、手順 2 で示したコマンド シーケンスを変更して、トレース セッションから削除するドライバー スタックに対応する「logman update」行を削除します。

解説

USB 3.0 ドライバー スタック イベントのキャプチャ フィルター

Logman キャプチャ コマンドの Default や PartialDataBusTrace などの ETW キーワードに注意してください。 これらの単語は、表示するイベントの種類を示す ETW キーワードです。 ETW キーワードを使用して、USB ドライバーがトレース ログに書き込むイベントをフィルター処理し、USB 3.0 ドライバー スタックからキャプチャされたイベントに関して表示する情報の量をカスタマイズできます。 キーワードのいずれかに一致するイベントが保存されます。 このフィルター処理方法は、分析時ではなくキャプチャ時に使用されます。

要件に応じて、キーワードに基づいてイベントをフィルター処理できます。 USB 3.0 ドライバー スタック イベントをフィルター処理するためのキーワードを次に示します。

ETW キーワード 説明
既定値 一般的なトラブルシューティングに役立つイベントを示します。 イベントは USB 2.0 ETW イベントに似ていますが、USB 転送イベントは含まれません。
StateMachine ドライバー内部ステート マシンの遷移を示します。 イベントは既定のキーワードには含まれません。
ランダウン トレースの開始時にデバイス情報イベントを表示し、USB ツリーの開始状態をキャプチャします。 デバイス情報のランダウン イベントは、接続されているデバイスの USB 記述子や USB デバイスの説明などの詳細がトレースに含まれるように保存することが重要です。 これらのイベントは既定のキーワードには含まれません。 既定のキーワードを使用しない場合は、ランダウン キーワードを使用する必要があります。 残りのランダウン イベントは、ドライバー内部ステート マシンの最近の状態遷移に関する情報を提供します。 これらのイベントは StateMachine キーワードには含まれません。
パワー 既定のイベントのサブセットを表示します。 デバイスの電源切り替えイベントを表示します。
IRP 既定のイベントのサブセットを表示します。 イベントには、クライアント ドライバーからの IRP と、ユーザー モード要求の結果の IRP が表示されます。 ただし、有効な USB 転送 (URB) 要求は IRP キーワードでは表示されず、表示するには HeadersBusTrace、PartialDataBusTrace、または FullDataBusTrace が必要です。
HeadersBusTrace すべての USB 転送イベントを表示しますが、データ パケットは保存されません。
PartialDataBusTrace すべての USB 転送イベントを表示し、バス データの限られたペイロードを保存します。
FullDataBusTrace すべての USB 転送イベントを表示し、一括転送、割り込み、制御転送のために最大 4 KB のバス データを保存します。 チェーンされた MDL の最初のバッファーのみがログに記録されることに注意してください。 等時性バス データはログに記録されません (ただし、URB_ISOCH_TRANSFER 要求構造は保存されます)。 詳細については、「チェーンされた MDL を送信する方法」および「USB 等時性エンドポイントにデータを転送する方法」を参照してください。
HWVerifyHost 既定のイベントのサブセットを表示します。 このイベントは、USB ホスト コントローラー ハードウェアでエラーが発生した場合を示します。
HWVerifyHub 既定のイベントのサブセットを表示します。 イベントは、USB ハブ ハードウェアでエラーが発生した場合を示します。
HWVerifyDevice 既定のイベントのサブセットを表示します。 イベントは、USB デバイス ハードウェアでエラーが発生した場合を示します。

例として、USB デバイスの電源遷移をキャプチャするセッションを開始する一連のコマンドを次に示します。 プロバイダー (USB 3.0 ドライバー スタック) の選択により、イベントは USB 3.0 ホスト コントローラーの下流に接続されているデバイスについてのみキャプチャされます。

logman create trace -n usbtrace -o %SystemRoot%\Tracing\usbtrace.etl -nb 128 640 -bs 128
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBXHCI (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3 (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-Kernel-IoTrace 0 2
logman start -n usbtrace

電源イベントのフィルターをキャプチャする

USB デバイスの便利な ETW キーワードは、USB ポート ドライバーの PowerDiagnostics フラグです。 このキーワードを使用すると、ポート ドライバーはホスト コントローラーとエンドポイントの情報をログに記録しますが、転送を記述するすべてのイベントを省略します。 転送イベントを表示する必要がない場合は、PowerDiagnostics キーワードを使用して、トレース ログのサイズを最大 85% 削減できます。 次の例に示すように、トレースを開始するときにPowerDiagnostics キーワードを指定します。

Logman start Usbtrace -p Microsoft-Windows-USB-USBPORT PowerDiagnostics -o usbtrace.etl -ets -nb 128 640 -bs 128

Logman update Usbtrace -p Microsoft-Windows-USB-USBHUB –ets

フィルター処理されたトレース ログにホスト コントローラの非同期スケジュールの有効化および無効化イベントが多数含まれている場合は、次の例に示すように、ログを表示するときに Netmon フィルタを使用してそれらのイベントをフィルター処理して除外できます。

NOT (Description == "USBPort_MicrosoftWindowsUSBUSBPORT:Host Controller Async Schedule Enable"
OR Description == "USBPort_MicrosoftWindowsUSBUSBPORT:Host Controller Async Schedule Disable")

Netmon でフィルターを使用する方法の詳細については、「ケース スタディ: ETW と Netmon の使用による不明な USB デバイスのトラブルシューティング」の「USB Netmon フィルター」を参照してください。

XACT エラーやストールなどのエラーを引き起こすハブ要求や、デバイス要求などの転送イベントをトレース ログに記録すると便利な場合があります。 最初に転送イベントなしでログをキャプチャし、その小さいログを分析できます。 次に、問題シナリオの問題を一般的に理解した後、フィルター処理を行わずにトレースを再実行します。