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

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

Winscope est un outil Web qui permet aux utilisateurs d'enregistrer, de rejouer 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 trace. À l'aide de l'interface utilisateur Winscope avec le fichier de trace, vous pouvez inspecter l'état de ces services pour chaque image d'animation, avec ou sans enregistrement d'écran, en rejouant, en parcourant et en déboguant les transitions.

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

SurfaceFlinger
Gestionnaire de fenêtres
WMShell
IME
Lanceur

Exécutez la visionneuse de traces Winscope

Le traçage Winscope fait partie des services de la plateforme. Cette section décrit les étapes requises pour télécharger, créer et exécuter la visionneuse de traces Winscope.

Suivez ces étapes pour configurer votre PC pour exécuter le traceur Winscope :

Téléchargez la source Android .
Accédez au dossier Winscope :
```
cd development/tools/winscope
```
Installez les dépendances en utilisant :
```
npm install
```
Pour voir une liste des commandes disponibles, exécutez : npm run
Créez toutes les cibles de production et de test en utilisant :
```
npm run build:all
```
Exécutez Winscope en utilisant :
```
npm run start
```

Capturer des traces

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

Capturer des traces sur l'appareil

Capturez des traces sur l'appareil pour collecter des données lors du dépôt de bogues pour des problèmes d'animation. Toutes les traces de l'interface utilisateur sont enregistrées avec cette méthode, car la configuration ne peut pas être personnalisée.

Sur votre appareil Android :

Activez les options du développeur .
Sélectionnez Suivi du système sous Options du développeur .
Activez Collecter les traces Winscope .
Sous Divers :
1. Activez Joindre des enregistrements aux rapports de bugs .
2. Activez Afficher la vignette Paramètres rapides .
Accédez à l’endroit où vous devez reproduire le bogue.
Pour démarrer la capture, ouvrez Paramètres rapides et sélectionnez Enregistrer la trace :
Figure 1. Menu de configuration rapide avec Record Trace.
Exécutez uniquement les étapes nécessaires pour reproduire le bug.
Pour arrêter la capture, ouvrez Paramètres rapides et sélectionnez Arrêter le traçage .
Partagez le journal capturé à l'aide de l'une des options répertoriées, telles que 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 de périphériques via USB ou Wi-Fi.

Sur Winscope :

Sur l'écran Collecter les traces , cliquez sur Proxy ADB :
Figure 2. Capturez des traces sur Winscope.
Lancez le proxy Winscope ADB Connect pour capturer les traces directement depuis votre navigateur.
Remarque : Python 3.5+ et ADB sont requis.

Exécutez la commande :

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

Pour démarrer la capture, sur l'écran Collecter les traces, sélectionnez les cibles et la configuration et cliquez sur Démarrer la trace :
Figure 3. Collectez des traces sur Winscope.
Pour arrêter la capture, cliquez sur Fin de trace :
Figure 4. Terminer la trace sur Winscope.

Lorsque l'outil télécharge les traces sur l'interface utilisateur de Winscope, les messages de récupération et d'analyse des fichiers proto apparaissent à l'écran.

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

Pour effectuer un vidage d'état à l'aide de Winscope, sur l'écran Collecter les traces, sélectionnez l'onglet Dump , puis cliquez sur Dump state :

dump-winscope

Figure 5. État de vidage sur Winscope.

Capturez des traces via les commandes adb

Exécutez adb root avant d’exécuter les commandes adb shell pour chacune des traces suivantes. A la fin de la trace, les fichiers de trace sont disponibles dans /data/misc/wmtrace . Pour copier un fichier ou un répertoire et ses sous-répertoires depuis un périphérique, voir Copier des fichiers vers et depuis un périphérique . Voir adb pour plus d'informations.

Traces WindowManager

Pour capturer les traces WindowManager :

Activer la trace :
```
adb shell wm tracing start
```
Désactiver 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
```
Enregistrer la trace une fois par image :
```
adb shell wm tracing frame
```
Enregistrez 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 :

Démarrez ProtoLog :
```
adb shell cmd window logging start
```
Arrêtez ProtoLog :
```
adb shell cmd window logging stop
```
Activez ProtoLog pour des 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 des 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 :

Démarrez ProtoLog :

adb shell dumpsys activity service SystemUIService WMShell

Traçage des transitions

Les commandes suivantes sont utilisées pour le traçage des transitions :

Dans le processus system_server :

Démarrer une trace :

adb shell cmd window shell tracing start

Arrêter 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 méthode 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 suivi IME pour les clients de méthode de saisie (IM), le service de méthode de saisie (IMS) et le service de gestion de méthode de saisie (IMMS) :
```
adb shell ime tracing start
```
Commencez à suivre les clients IME, IMS et IMMS :
```
adb shell ime tracing stop
```

Couches SurfaceFlinger

Le traçage des couches SurfaceFlinger utilise la trace Perfetto pour la capture. Voir Configuration de trace pour obtenir des informations sur la configuration.

Consultez l’exemple suivant de configuration pour le traçage de 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 pour générer le traçage des 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. Voir Configuration de trace pour obtenir des informations sur la configuration.

Voir l'exemple suivant de configuration Perfetto 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

Voir l'exemple suivant de configuration Perfetto pour le traçage continu 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 pour générer le suivi des 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 WindowManager et SurfaceFlinger à partir des rapports de bogues. Les rapports de bogues 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 invalides qui provoquent des problèmes d'animation, Winscope regroupe différents fichiers de trace, propose une recherche et une visualisation sur les images et les chronologies, et présente les messages protobuf de manière cohérente. L'analyse des traces dans Winscope permet d'identifier la couche, l'image et l'état exacts de l'occurrence du bogue.

Utiliser Winscope

Lorsque vous avez capturé des traces , analysez les traces sur Winscope :

Téléchargez vos traces enregistrées en utilisant le panneau de droite. Vous pouvez supprimer les traces téléchargées ou télécharger davantage de traces.
Remarque : Les types de fichiers de trace pris en charge sont les traces Winscope, les vidéos MP4 avec des métadonnées Winscope (collectées avec adb), les fichiers zip et les rapports de bogues.
Figure 6. Téléchargez des traces sur Winscope.
Cliquez sur Afficher les traces pour visualiser les traces téléchargées. Des onglets pour chaque trace apparaissent sur le panneau supérieur de la fenêtre. Si le fichier téléchargé contient les traces pertinentes, une vue flottante de la trace de l'enregistrement d'écran est superposée à l'écran.
Figure 7. Afficher les traces sur Winscope.
Utilisez l'interface utilisateur sur le panneau supérieur de la fenêtre pour renommer et téléchargez votre trace téléchargée ou pour en télécharger un nouveau.
Parcourez les traces au fil du temps à l’aide de l’outil de curseur temporel 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 à une heure ou une occurrence particulière, utilisez le curseur (curseur temporel) ou le bouton gauche et c'est vrai flèches dans la zone d’affichage de l’heure (coin inférieur gauche) ou flèches gauche et droite de votre clavier.
- Pour afficher les traces codées par couleur sélectionnées sur la chronologie, utilisez le menu déroulant (à gauche du curseur temporel). Par défaut, les trois dernières traces visualisées à l'aide des onglets de trace sont affichées sur la timeline.
- Pour une vue granulaire de toutes les traces téléchargées, utilisez le zoom avant ou effectuer un zoom arrière (sous le curseur temporel) ou faites défiler sur votre clavier. Utilisez le bouton de réinitialisation pour réinitialiser le niveau de zoom.
- Pour une vue développée de la distribution des traces dans le temps, cliquez sur la flèche vers le haut (le coin inférieur droit).
Figure 8. Navigation temporelle sur Winscope.
Dans la vue développée (Figure 9), sélectionnez et zoomez sur des périodes spécifiques 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 sur le panneau supérieur de l'outil.
- Pour le tracé Surface Flinger , trois panneaux affichent différentes vues du tracé à une période donnée, comme le montre la Figure 10 :
  Figure 10. Trace Surface Flinger sur Winscope.
  - Vue Calques : une vue 3D des calques en superpositions rectangulaires. Les éléments d'interface utilisateur suivants ajustent les rectangles pour restituer 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 Calques) fait pivoter les rectangles superposés pour les afficher sous les angles choisis.
    - Le curseur Espacement (en haut à droite de la vue Calques) ajuste l'espacement entre les calques pour créer la vue composite choisie.
    - Les outils de zoom (en haut à droite de la vue Calques) effectuent un zoom avant et dézoomer dans les couches pour une meilleure inspection.
    - Le bouton de réinitialisation (en haut à droite de la vue Calques) restaure les paramètres de la caméra à la vue d'origine.
    - Faites glisser les rectangles pour faciliter un meilleur zoom.
    Remarque : Les cases à cocher Uniquement visible et Afficher virtuel sont obsolètes.
  - Vue hiérarchique : une hiérarchie complète des couches.
    - Uniquement visible (en haut à droite de la vue Hiérarchie), lorsque cette option est sélectionnée, masque les calques invisibles de la hiérarchie pour faciliter la visualisation des éléments à l'écran.
    - Plat (en haut à droite de la vue Hiérarchie), lorsqu'il est sélectionné, affiche la hiérarchie sous la forme d'une liste aplatie de couches.
    - Afficher les différences (en haut à gauche de la vue Hiérarchie) est sélectionné uniquement en cas de transition d'état. Lorsqu'il est sélectionné, l'outil compare l'état actuel au précédent. Un nouvel élément est surligné en vert, un élément supprimé est surligné en rouge et un élément modifié est surligné en bleu.
  - Vue Propriétés : Propriétés du calque sélectionné. Le panneau supérieur de la vue Propriétés contient des informations uniquement sur les propriétés clés, telles que Visibility , Geometry et Buffer . Le panneau inférieur de la vue Propriétés contient un Proto Dump 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), lorsque sélectionné, affiche les valeurs de proto par défaut sur le Proto Dump. Par défaut, ces valeurs ne sont pas répertoriées dans le Proto Dump. Les valeurs de proto par défaut sont extraites de la définition du champ de proto. Si un champ proto n’a pas de valeur par défaut non nulle, les valeurs proto par défaut affichées sont :
      - Chaînes : Nul
      - Chiffres : 0
      - Valeurs booléennes : Faux
      - Objets : Nul
  La sélection entre les trois vues et l'enregistrement d'écran sont synchronisés, c'est-à-dire que toutes les traces sont mises à jour de manière synchrone lorsque vous naviguez vers un moment différent. Pour voir les propriétés d'un calque, sélectionnez le calque en cliquant dessus dans la vue Hiérarchie ou en cliquant sur le rectangle correspondant dans la vue Propriétés. Un rectangle violet indique qu'une trace de vue est attachée à ce calque. En double-cliquant sur un calque violet, l'interface utilisateur navigue pour passer à l'onglet de trace de vue approprié.
- Pour la trace Window Manager , trois panneaux affichent différentes vues de la trace à une période donnée, comme le montre la figure 11 :
  - Vue Windows : Une vue 3D des couches.
  - Vue hiérarchique : une hiérarchie complète des couches.
  - La vue Propriétés contient un Proto Dump de toutes les propriétés.
  La sélection entre les trois vues et l'enregistrement d'écran sont synchronisés, c'est-à-dire que toutes les traces sont mises à jour de manière synchrone lorsque vous naviguez vers un moment différent.
  Remarque : La fonction et l'emplacement des éléments de l'interface utilisateur sur les trois vues sont similaires à ceux de la trace Surface Flinger.
  Figure 11. Trace du gestionnaire de fenêtres sur Winscope.
- Pour les traces de transactions , les transactions entre Surface Flinger et Window Manager 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 montre le proto dump. La sélection entre les deux vues et l'enregistrement d'écran sont synchronisés :
  Figure 12. Trace des transactions sur Winscope.
- Pour les traces ProtoLog , les informations sont présentées sous forme de tableau, consultable par balises, fichiers sources et texte :
  Figure 13. Trace ProtoLog sur Winscope.
- Pour les traces de 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.