Cette page a été traduite par l'API Cloud Translation.

Tracer les transitions de fenêtres à l'aide de Winscope

Winscope est un outil Web qui permet aux utilisateurs d'enregistrer, de relire et d'analyser les états de plusieurs services système pendant et après les animations et les transitions. Winscope enregistre tous les états de service système pertinents dans un fichier de suivi. À l'aide de l'interface utilisateur Winscope avec le fichier de suivi, vous pouvez inspecter l'état de ces services pour chaque frame d'animation, avec ou sans enregistrement d'écran, en relisant, en parcourant les étapes et en déboguant les transitions.

Les services système qui produisent des traces pouvant être chargées dans Winscope sont les suivants :

SurfaceFlinger
WindowManager
WMShell
IME
Lanceur d'applications

Exécuter le lecteur de traces Winscope

Le traçage Winscope fait partie des services de la plate-forme. Cette section décrit les étapes à suivre pour télécharger, compiler et exécuter le lecteur de traces Winscope.

Procédez comme suit pour configurer votre PC afin qu'il exécute le traceur Winscope:

Téléchargez le code source Android.
Accédez au dossier Winscope:
```
cd development/tools/winscope
```
Installez les dépendances à l'aide de :
```
npm install
```
Pour afficher la liste des commandes disponibles, exécutez la commande suivante : npm run
Créez toutes les cibles de production et de test à l'aide des éléments suivants:
```
npm run build:prod
```
Exécutez Winscope à l'aide de :
```
npm run start
```

Capturer des traces

Vous pouvez capturer des traces sur l'appareil, via Winscope ou les commandes Android Debug Bridge (adb).

Capturer des traces sur l'appareil

Capturez des traces sur l'appareil pour collecter des données lorsque vous signalez des bugs liés à des problèmes d'animation. Toutes les traces de l'UI sont enregistrées avec cette méthode, car la configuration ne peut pas être personnalisée.

Sur votre appareil Android :

Activez les options pour les développeurs.
Sélectionnez System Tracing (Traçage système) sous "Developer options" (Options pour les développeurs).
Activez Collecter les traces Winscope.
Sous Divers :
1. Activez Joindre des enregistrements aux rapports de bug.
2. Activez l'option Afficher le bloc "Réglages rapides".
Accédez à l'emplacement où vous devez reproduire le bug.
Pour commencer la capture, ouvrez les Réglages rapides et sélectionnez Record trace (Enregistrer une trace) :

Figure 1 : Menu "Réglages rapides" avec l'option "Enregistrer la trace".
N'effectuez que les étapes nécessaires pour reproduire le bug.
Pour arrêter la capture, ouvrez les Réglages rapides, puis sélectionnez Arrêter le traçage.
Partagez le journal capturé à l'aide de l'une des options listées, comme Gmail, Drive ou BetterBug.

Capturer des traces via Winscope

Vous pouvez capturer des traces à l'aide de Winscope pour le développement et le débogage locaux. Winscope utilise adb, qui prend en charge la connexion d'appareil via USB ou Wi-Fi.

Sous Winscope:

Sur l'écran Collect Traces (Collecter les traces), cliquez sur ADB Proxy (Proxy ADB) :

Figure 2. Capturer des traces sur Winscope
Lancez le proxy Winscope ADB Connect pour capturer les traces directement à partir de votre navigateur.

Remarque :Python 3.5+ et ADB sont requis.

Exécutez la commande suivante:

python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py

Pour commencer la capture, sélectionnez les cibles et la configuration sur l'écran Collect Traces (Collecter les traces), puis cliquez sur Start trace (Démarrer une trace) :

Figure 3. Collectez des traces sur Winscope.
Pour arrêter la capture, cliquez sur End trace (Terminer la trace) :

Figure 4. Arrêtez la trace dans Winscope.

Lorsque l'outil importe les traces dans l'interface utilisateur de Winscope, les messages Récupération et Analyse des fichiers Proto s'affichent à l'écran.

Générer le dump d'état à l'aide de Winscope

Pour créer une copie d'état à l'aide de Winscope, sur l'écran Collect Traces (Collecter des traces), sélectionnez l'onglet Dump (Copie), puis cliquez sur Dump state (Copier l'état) :

dump-winscope

Figure 5. Videz l'état sur Winscope.

Capturer des traces via des commandes adb

Exécutez adb root avant d'exécuter les commandes adb shell pour chacune des traces suivantes. À la fin de la trace, les fichiers de suivi sont disponibles dans /data/misc/wmtrace. Pour copier un fichier ou un répertoire et ses sous-répertoires à partir d'un appareil, consultez Copier des fichiers vers et depuis un appareil. Pour en savoir plus, consultez adb.

Traces WindowManager

Pour capturer des traces WindowManager :

Activez la trace:
```
adb shell wm tracing start
```
Désactivez la trace:
```
adb shell wm tracing stop
```
Enregistrez les données de journalisation dans un fichier lors de l'exécution d'une capture de trace:
```
adb shell wm tracing save-for-bugreport
```
Consigner la trace une fois par trame:
```
adb shell wm tracing frame
```
Journalisez chaque transaction :
```
adb shell wm tracing transaction
```
Définissez la taille maximale du journal (en Ko):
```
adb shell wm tracing size
```
État de la trace d'impression :
```
adb shell wm tracing status
```
Définissez le niveau de journalisation sur critical (uniquement les fenêtres visibles avec des informations réduites), trim (toutes les fenêtres avec des informations réduites) ou all (toutes les fenêtres et informations):
```
adb shell wm tracing level
```

ProtoLog.

Les commandes suivantes sont utilisées pour le système ProtoLog.

Dans le processus system_server :

Lancez ProtoLog:
```
adb shell cmd window logging start
```
Arrêter ProtoLog:
```
adb shell cmd window logging stop
```
Activez ProtoLog pour les groupes de journaux donnés :
```
adb shell cmd window logging enable [group...]
```
Désactivez ProtoLog pour des groupes de journaux donnés:
```
adb shell cmd window logging disable [group...]
```
Activez la journalisation Logcat pour les groupes de journaux donnés:
```
adb shell cmd window logging enable-text [group...]
```
Désactivez la journalisation Logcat pour des groupes de journaux donnés:
```
adb shell cmd window logging disable-text [group...]
```

Dans WMShell :

Lancez ProtoLog:

adb shell dumpsys activity service SystemUIService WMShell

Traçage de transition

Les commandes suivantes sont utilisées pour le traçage de transition:

Dans le processus system_server :

Démarrez une trace:

adb shell cmd window shell tracing start

Arrêtez une trace:

adb shell cmd window shell tracing stop

Démarrez une trace dans WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

Arrêtez une trace dans WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

éditeur de mode de saisie

Les commandes suivantes sont utilisées pour le traçage de l'éditeur de méthode d'entrée (IME) :

Démarrez le traçage IME pour les clients de mode de saisie, le service de mode de saisie (IMS) et le service de gestion du mode de saisie (IMMS) :
```
adb shell ime tracing start
```
Commencez à tracer les clients IME, IMS et IMMS:
```
adb shell ime tracing stop
```

Calques SurfaceFlinger

Le traçage de la couche SurfaceFlinger utilise la trace Perfetto pour la capture. Pour en savoir plus sur la configuration, consultez la page Configuration de la traçabilité.

Consultez l'exemple de configuration suivant pour le traçage de la couche SurfaceFlinger :

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

Consultez l'exemple de commande suivant afin de générer un traçage pour les couches SurfaceFlinger:

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

Transactions SurfaceFlinger

Le traçage des transactions SurfaceFlinger utilise la trace Perfetto pour la capture. Consultez la section Configuration de Trace pour obtenir des informations sur la configuration.

Consultez l'exemple de configuration Perfetto suivant pour le traçage actif SurfaceFlinger :

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

Consultez l'exemple de configuration Perfetto suivant pour le traçage continu de SurfaceFlinger :

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

Consultez l'exemple de commande suivant afin de générer un traçage pour les transactions SurfaceFlinger:

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

Générer un vidage d'état à l'aide d'adb

Winscope lit un instantané des états de WindowManager et de SurfaceFlinger à partir des rapports de bugs. Les rapports de bugs stockent les états sous forme de fichiers proto distincts dans le dossier proto. Pour générer les vidages d'état à l'aide d'adb, exécutez les commandes suivantes.

Pour WindowManager:

adb exec-out dumpsys window --proto > window_dump.winscope

Pour SurfaceFlinger:

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

Analyser les traces

Pour déboguer les états transitoires et non valides qui causent des problèmes d'animation, Winscope agrège différents fichiers de trace, fournit des fonctionnalités de recherche et de visualisation sur les frames et les chronologies, et présente les messages protobuf de manière cohérente. L'analyse des traces dans Winscope permet d'identifier précisément la couche, l'image et l'état de l'occurrence du bug.

Utiliser Winscope

Une fois que vous avez capturé des traces, analysez-les dans Winscope :

Importez vos traces enregistrées à l'aide du panneau de droite. Vous pouvez supprimer les traces importées ou en importer d'autres.

Remarque : Les types de fichiers de trace acceptés sont les traces Winscope, les vidéos MP4 avec métadonnées Winscope (collectées avec adb), les fichiers ZIP et les rapports de bugs.

Figure 6. Importez des traces sur Winscope.
Cliquez sur Afficher les traces pour visualiser les traces importées. Les onglets de chaque trace apparaissent dans le panneau supérieur de la fenêtre. Si le fichier importé contient les traces pertinentes, une vue flottante de la trace d'enregistrement de l'écran est superposée à l'écran.

Figure 7. Afficher les traces sur Winscope.

Utilisez l'interface utilisateur dans le panneau supérieur de la fenêtre pour renommer et télécharger la trace importée , ou en importer un nouveau.
Parcourez les traces au fil du temps à l'aide du curseur de temps situé dans le panneau inférieur de la fenêtre. Pour une navigation temporelle supplémentaire, utilisez les fonctionnalités suivantes, comme illustré dans la figure 8 :
- Pour accéder à un événement ou à une heure spécifique, utilisez le curseur (sélecteur de temps), ou les flèches vers la gauche et vers la droite dans le champ d'affichage de l'heure (en bas à gauche), ou les flèches vers la gauche et vers la droite sur votre clavier.
- Pour afficher les traces sélectionnées avec un code couleur sur la chronologie, utilisez le menu déroulant (à gauche du curseur de temps). Par défaut, les trois dernières traces consultées à l'aide des onglets de trace sont affichées dans la chronologie.
- Pour obtenir une vue détaillée de toutes les traces importées, utilisez l'outil de zoom avant ou de zoom arrière (sous le curseur chronologique), ou faites défiler le clavier. Utilisez le bouton de réinitialisation pour réinitialiser le niveau de zoom.
- Pour afficher une vue développée de la distribution des traces au fil du temps, cliquez sur la flèche vers le haut (en bas à droite).
Figure 8. Navigation temporelle sur Winscope

Dans la vue développée (figure 9), sélectionnez des périodes spécifiques et faites un zoom avant pour une meilleure inspection:

Figure 9. Chronologie étendue sur Winscope.
Pour examiner les traces, vous pouvez afficher l'état de l'appareil avec l'enregistrement d'écran. Pour examiner une trace particulière, cliquez sur l'onglet de trace correspondant dans le panneau supérieur de l'outil.
- Pour la trace Surface Flinger, trois panneaux affichent différentes vues de la trace à un moment donné, comme illustré dans la figure 10 :
  
  Figure 10. Trace Surface Flinger sur Winscope.
  - Vue Layers (Calques) : vue 3D des calques des superpositions rectangulaires. Les éléments d'interface utilisateur suivants ajustent les rectangles pour afficher les éléments graphiques en termes de position, de taille, de transformation et d'ordre Z :
    - Le curseur Rotation (en haut à gauche de la vue des couches) fait pivoter les rectangles superposés pour les afficher selon les angles choisis.
    - Le curseur Spacing (Espacement) (en haut à droite de la vue Layers) ajuste l'espacement entre les calques pour créer la vue composite choisie.
    - Les outils de zoom (en haut à droite de la vue "Calques") permettent de faire un zoom avant et un zoom arrière dans les calques pour mieux les inspecter.
    - Le bouton de réinitialisation (en haut à droite de la vue des calques) restaure les paramètres de la caméra à la vue d'origine.
    - Faites glisser les rectangles pour faciliter le zoom.
    Remarque : Les cases à cocher Uniquement les éléments visibles et Afficher les éléments virtuels sont obsolètes.
  - Vue Hiérarchie : hiérarchie complète des calques.
    - Uniquement les éléments visibles (en haut à droite de la vue "Hiérarchie") permet, lorsqu'il est sélectionné, de masquer les calques invisibles de la hiérarchie pour faciliter la visualisation des éléments à l'écran.
    - Flat (Aplat) (en haut à droite de la vue "Hierarchy") : affiche la hiérarchie sous la forme d'une liste aplatie de calques.
    - L'option Show diff (Afficher les différences) (en haut à gauche de la vue "Hierarchy") n'est sélectionnée que lorsqu'il existe une transition d'état. Lorsqu'il est sélectionné, l'outil compare l'état actuel à l'état précédent. Un nouvel élément est surligné en vert, un élément supprimé en rouge et un élément modifié en bleu.
  - Vue Properties (Propriétés) : propriétés du calque sélectionné. Le panneau supérieur de la vue Propriétés ne contient que des informations sur les propriétés clés, telles que Visibilité, Géométrie et Tampon. Le panneau inférieur de la vue Properties (Propriétés) contient un vidage des prototypes de toutes les propriétés.
    - La case à cocher Afficher les différences (en haut à gauche de la vue "Propriétés") se comporte comme dans la vue Hiérarchie.
    - Afficher les valeurs par défaut (en haut à gauche de la vue "Propriétés") affiche les valeurs par défaut du protocole dans le dump de protocole. Par défaut, ces valeurs ne sont pas listées dans le dump de protocole. Les valeurs proto par défaut sont extraites de la définition du champ proto. Si aucune valeur par défaut non nulle n'est définie pour un champ proto, les valeurs proto par défaut affichées sont les suivantes :
      - Chaînes : "Null"
      - Chiffres : 0
      - Valeurs booléennes: False
      - Objets: nuls
  La sélection entre les trois vues et l'enregistrement d'écran est synchronisée, c'est-à-dire que toutes les traces sont mises à jour de manière synchrone lorsque vous accédez à un autre moment. Pour afficher les propriétés d'un calque, sélectionnez-le en cliquant dessus dans la vue "Hiérarchie" ou sur le rectangle correspondant dans la vue "Propriétés". Un rectangle violet indique qu'une trace de vue est associée à cette couche. Lorsque vous double-cliquez sur un calque violet, l'UI passe à l'onglet approprié de la trace de la vue.
- Pour la trace du gestionnaire de fenêtres, trois panneaux affichent différentes vues de la trace à une période donnée, comme illustré dans la figure 11:
  - Vue Windows: vue 3D des calques.
  - Vue Hierarchy (Hiérarchie) : hiérarchie complète des calques.
  - La vue Properties (Propriétés) contient un dump de proto de toutes les propriétés.
  La sélection entre les trois vues et l'enregistrement d'écran est synchronisée. En d'autres termes, toutes les traces sont mises à jour de manière synchrone lorsque vous accédez à un moment différent.
  
  Remarque :La fonction et le placement des éléments d'interface utilisateur sur les trois vues sont semblables à ceux de la trace Surface Flinger.
  
  Figure 11 : Trace du gestionnaire de fenêtres sur Winscope.
- Pour les traces Transactions, les transactions entre Surface Flinger et le gestionnaire de fenêtres sont présentées sous forme de tableau, qui peut être recherché par les ID, le type et le texte affichés, ainsi qu'une vue des propriétés qui affiche le dump de proto. La sélection entre les deux vues et l'enregistrement d'écran est synchronisée:
  
  Figure 12. Traçage des transactions dans Winscope.
- Pour les traces ProtoLog, les informations sont présentées sous forme de table dans laquelle vous pouvez effectuer des recherches par balises, fichiers sources et texte:
  
  Figure 13. Trace ProtoLog sur Winscope
- Pour les traces Transitions, une liste de transitions avec l'ID, le type, l'heure d'envoi, la durée et l'état s'affiche, ainsi que les propriétés de la transition sélectionnée :
  
  Figure 14. Trace des transitions sur Winscope