Partager via

Comment capturer une trace d’événement USB avec Logman

  • Article

Cet article fournit des informations sur l’utilisation de l’outil Logman pour capturer une trace d’événement ETW USB. Logman est un outil de suivi intégré à Windows. Vous pouvez utiliser Logman pour capturer des événements dans un fichier journal de trace d’événements.

Prérequis

Les fichiers journaux de suivi des événements peuvent croître très rapidement, mais un fichier journal plus petit est plus facile à parcourir et plus facile à transmettre. Avant de commencer une trace, envisagez d’effectuer les étapes suivantes pour exclure les événements superflus du journal afin de pouvoir vous concentrer sur l’activité de l’appareil que vous souhaitez examiner :

  • Déconnectez tous les périphériques USB non critiques qui ne sont pas l’appareil qui vous intéresse. Moins d’appareils entraînent des traces plus petites, ce qui facilite la lecture et l’analyse.
  • Si votre système dispose d’un clavier ou d’une souris USB, entrez les commandes de trace à l’aide du Bureau à distance à la place.
  • Limitez autant que possible le début et la fin de la trace autour des opérations qui vous intéressent.
  • Si vous n’êtes intéressé que par une certaine catégorie d’événements USB, vous pouvez utiliser des mots clés pour filtrer les événements enregistrés. Pour plus d'informations, consultez la section Notes.

Les traces d’événements de la pile de pilotes USB 3.0 sont similaires aux traces de pile de pilotes USB 2.0, qui ont été introduites dans Windows 7. Les traces d’événements de la pile de pilotes USB 2.0 peuvent être capturées sur un ordinateur Windows 8. La façon dont vous capturez les traces d’événements à partir des piles de pilotes USB 2.0 et USB 3.0 est similaire. Vous pouvez capturer des événements à partir de la pile de pilotes USB 2.0 ou USB 3.0 indépendamment. Lorsque vous connectez un appareil USB 2.0 à un contrôleur hôte USB 3.0, vous obtenez des traces d’événements à partir de la pile de pilotes USB 3.0. Dans ce cas, vous verrez les nouveaux événements de pile de pilotes USB 3.0 pour un appareil USB 2.0.

Instructions

Pour collecter des événements de trace USB

  1. Ouvrez une fenêtre d’invite de commandes qui dispose de privilèges d’administration. Pour ce faire, sélectionnez Démarrer, tapez cmd dans la zone de recherche, Sélectionnez et maintenez le bouton droit (ou cliquez avec le bouton droit) cmd.exe, puis sélectionnez Exécuter en tant qu’administrateur.

  2. Dans la fenêtre d’invite de commandes, entrez ces commandes pour démarrer une session de capture :

    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

    Une fois chacune de ces commandes terminée, Logman affiche The command completed successfully.

  3. Effectuez les opérations que vous souhaitez capturer. Par exemple, pour capturer des événements pour l’énumération d’appareil, vous pouvez brancher un lecteur flash USB qui s’affiche sous la forme d’un « appareil inconnu » dans Gestionnaire de périphériques. Gardez la fenêtre d’invite de commandes ouverte.

  4. Arrêtez la session une fois que vous avez terminé le scénario. Entrez ces commandes pour mettre fin à la session de capture :

    Vous pouvez arrêter la collecte d’événements de hub et de port USB en exécutant la commande suivante :

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

La session de capture précédente génère un fichier etl, nommé usbtrace.etl. Le fichier de trace est stocké dans %SystemRoot%\Tracing\usbtrace.etl (C :\Windows\Tracing\usbtrace.etl). Déplacez le fichier à un autre emplacement ou renommez-le afin d’éviter de le remplacer lors de la capture de la session suivante.

Le fichier contient des traces d’événements provenant des piles de pilotes USB 3.0 et USB 2.0. Si vous souhaitez réduire les traces d’événements à une seule pile de pilotes USB, supprimez l’autre pile de pilotes de votre prochaine session de suivi. Pour ce faire, modifiez la séquence de commandes indiquée à l’étape 2 pour supprimer les lignes « logman update » correspondant à la pile de pilotes que vous souhaitez supprimer de la session de trace.

Remarques

Filtres de capture pour les événements de pile de pilotes USB 3.0

Notez les mots clés ETW tels que Default et PartialDataBusTrace dans les commandes de capture Logman. Ces mots sont des mots clés ETW qui indiquent les types d’événements que vous souhaitez afficher. Vous pouvez utiliser des mots clés ETW pour filtrer les événements que les pilotes USB écrivent dans un journal de suivi et personnaliser la quantité d’informations que vous souhaitez afficher sur les événements capturés à partir de la pile de pilotes USB 3.0. Les événements qui correspondent à l’un de vos mots clés sont enregistrés. Notez que cette méthode de filtrage est destinée à être utilisée au moment de la capture, et non pendant l’analyse.

Vous pouvez filtrer les événements en fonction de mots clés en fonction de vos besoins. Voici des mots clés pour filtrer les événements de pile de pilotes USB 3.0 :

MOT CLÉ ETW Description
Par défaut Affiche les événements utiles pour la résolution des problèmes généraux. Les événements sont similaires aux événements ETW USB 2.0, mais n’incluent pas d’événements de transfert USB.
StateMachine Affiche les transitions de la machine à état interne du pilote. Les événements ne sont pas inclus dans le mot clé par défaut.
Délabré Affiche les événements d’informations sur l’appareil au début de la trace et capture l’état de départ de l’arborescence USB. Les événements d’exécution des informations sur l’appareil sont importants à enregistrer afin que la trace contienne des détails, tels que les descripteurs USB et la description de périphérique USB, des appareils connectés. Ces événements sont inclus dans le mot clé par défaut. Lorsque vous n’utilisez pas le mot clé par défaut, vous devez utiliser le mot clé d’exécution. Les événements Rundown restants fournissent des informations sur les transitions d’état récentes des machines d’état internes aux pilotes. Ces événements sont inclus dans le mot clé StateMachine.
Power Affiche un sous-ensemble d’événements par défaut . Affiche les événements de transition d’alimentation de l’appareil.
IRP Affiche un sous-ensemble d’événements par défaut . Les événements affichent les IRPs du pilote client et les IRPs résultant des demandes en mode utilisateur. Toutefois, les demandes de transfert USB (URB) valides ne sont pas affichées avec le mot clé IRP et nécessitent HeadersBusTrace, PartialDataBusTrace ou FullDataBusTrace pour être affichées.
En-têtesBusTrace Affiche tous les événements de transfert USB, mais n’enregistre pas les paquets de données.
PartialDataBusTrace Affiche tous les événements de transfert USB et enregistre une charge utile limitée de données de bus.
FullDataBusTrace Affiche tous les événements de transfert USB et enregistre jusqu’à 4 Ko de données de bus pour les transferts en bloc, les interruptions et les transferts de contrôle. Notez que seule la première mémoire tampon d’une MDL chaînée est journalisée. Les données de bus isochronous ne sont jamais journalisées (bien que la structure de requête URB_ISOCH_TRANSFER soit enregistrée). Pour plus d’informations, consultez Comment envoyer des dll MDL chaînées et Comment transférer des données vers des points de terminaison isochronaux USB.
HWVerifyHost Affiche un sous-ensemble d’événements par défaut . Les événements indiquent quand une erreur se produit dans le matériel du contrôleur hôte USB.
HWVerifyHub Affiche un sous-ensemble d’événements par défaut . Les événements indiquent quand une erreur se produit dans le matériel du hub USB.
HWVerifyDevice Affiche un sous-ensemble d’événements par défaut . Les événements indiquent quand une erreur se produit dans le matériel du périphérique USB.

Par exemple, voici une séquence de commandes qui démarrent une session pour capturer les transitions d’alimentation des périphériques USB. En raison de la sélection de fournisseurs (la pile de pilotes USB 3.0), les événements sont capturés uniquement pour les appareils connectés en aval d’un contrôleur hôte 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

Filtres de capture pour les événements power

Un mot clé ETW utile pour les périphériques USB est l’indicateur PowerDiagnostics du pilote de port USB. Lorsque vous utilisez cette mot clé, le pilote de port consigne les informations sur l’hôte-contrôleur et le point de terminaison, mais omet tous les événements qui décrivent les transferts. Si vous n’avez pas besoin de voir les événements de transfert, vous pouvez utiliser l’mot clé PowerDiagnostics pour réduire la taille d’un journal de suivi jusqu’à 85 %. Spécifiez le mot clé PowerDiagnostics lorsque vous démarrez la trace, comme illustré dans l’exemple suivant :

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

Si votre journal de trace filtré a de nombreux événements de planification asynchrone du contrôleur hôte, vous pouvez les filtrer lors de l’affichage du journal à l’aide d’un filtre Netmon, comme illustré dans l’exemple suivant :

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

Pour plus d’informations sur les filtres Netmon, consultez « Filtres NETmon USB » dans Étude de cas : Résolution des problèmes d’un périphérique USB inconnu à l’aide d’ETW et Netmon.

Il est parfois utile d’avoir les événements de transfert dans votre journal de suivi, tels que les demandes hub et les demandes d’appareil qui entraînent des erreurs telles qu’une erreur XACT ou un blocage. Vous pouvez d’abord capturer un journal sans les événements de transfert et analyser ce journal plus petit. Réexécutez ensuite la trace sans filtrage une fois que vous avez une compréhension générale des problèmes dans votre scénario de problème.