Capturer des traces avec des commandes adb

Vous pouvez collecter des traces Winscope à l'aide de la ligne de commande adb sur les builds de débogage (c'est-à-dire les builds userdebug et eng). Avant de collecter des traces Winscope avec adb, exécutez adb root.

À partir d'Android 15, les traces Winscope sont intégrées à Perfetto et collectées à l'aide de la ligne de commande Perfetto. Chaque trace Winscope est une source de données Perfetto avec sa propre configuration. Vous pouvez activer les configurations individuellement ou dans une seule session de traçage.

Dans Android 14 et versions antérieures, chaque trace Winscope possède une commande différente et vous pouvez collecter chacune d'elles indépendamment. Pour en savoir plus, consultez la section Capturer des traces dans Android 14 et versions antérieures.

WindowManager

Utilisez le nom de source de données android.windowmanager pour ce type de trace.

Options de configuration

  • Niveau de journalisation (log_level) : spécifie la verbosité du journal. Valeurs acceptées :

    • LOG_LEVEL_VERBOSE: enregistre tous les éléments avec le maximum d'informations.
    • LOG_LEVEL_DEBUG: enregistre tous les éléments, mais n'écrit pas toutes les données de configuration.
    • LOG_LEVEL_CRITICAL: enregistre uniquement les éléments visibles, avec le minimum de surcharge de performances.

  • Fréquence de journalisation (log_frequency) : définit la fréquence à laquelle les éléments sont enregistrés :

    • LOG_FREQUENCY_FRAME : suit les instantanés d'état lorsqu'un frame est validé.
    • LOG_FREQUENCY_TRANSACTION: suit les instantanés d'état chaque fois qu'une transaction est validée.
    • LOG_FREQUENCY_SINGLE_DUMP: suit les instantanés d'état uniques lorsque la source de données est démarrée.

Pour en savoir plus sur les valeurs de configuration, consultez WindowManager.

Exemple

L'exemple suivant montre le type de trace WindowManager pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

Utilisez le nom de source de données android.protolog pour ce type de trace.

Options de configuration

Mode de traçage (tracing_mode) : détermine la configuration de journalisation à utiliser :

  • DEFAULT: suit uniquement les groupes et les niveaux de journalisation spécifiés dans group_overrides.
  • ENABLE_ALL: suit tous les groupes et niveaux de journalisation, sauf indication contraire dans group_overrides.

Niveau de journalisation minimal (default_log_from_level) : si cette option est définie, tout message dont le niveau de journalisation est supérieur ou égal à ce niveau est suivi, sauf si une substitution de groupe est spécifiée. Par exemple, cette option permet d'activer la journalisation de tous les avertissements et erreurs sans avoir à activer tous les journaux. Les valeurs acceptées sont les suivantes :

  • PROTOLOG_LEVEL_DEBUG
  • PROTOLOG_LEVEL_VERBOSE
  • PROTOLOG_LEVEL_INFO
  • PROTOLOG_LEVEL_WARN
  • PROTOLOG_LEVEL_ERROR
  • PROTOLOG_LEVEL_WTF

Substitutions de groupe (group_overrides) : permet de configurer manuellement le niveau de journalisation pour chaque groupe ProtoLog. Chaque groupe contient les éléments suivants :

  • name : nom du groupe ProtoLog, utilisé dans le code source Android.
  • log_from : identique à default_log_from_level, mais spécifié uniquement pour le groupe actuel.

  • collect_stacktrace: lorsque cette option est définie sur true, elle collecte la trace de la pile pour chaque message ProtoLog du groupe suivi.

Exemple

L'exemple suivant montre le type de trace ProtoLog pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

Entrée

Utilisez le nom de source de données android.input.inputevent pour ce type de trace.

Options de configuration

Mode de trace (trace_mode) : détermine si la trace d'entrée doit être démarrée à l'aide de règles préservant la confidentialité ou enregistrer tous les événements d'entrée :

  • TRACE_MODE_TRACE_ALL: enregistre tous les événements d'entrée traités par le système, quel que soit le contexte dans lequel ils ont été traités.
  • TRACE_MODE_USE_RULES: utilise les règles de traçage définies dans cette configuration pour spécifier les événements à suivre. Pour en savoir plus sur la spécification des règles de la trace, consultez android_input_event_config.proto.

Exemple

Voici un exemple du type de trace d'entrée pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger (calques)

Utilisez le nom de source de données android.surfaceflinger.layers pour ce type de trace.

Options de configuration

Mode de traçage (mode) : définit la fréquence à laquelle les éléments sont enregistrés :

  • MODE_ACTIVE : suit les instantanés des calques. Un instantané est pris chaque fois qu'un calque est modifié.
  • MODE_GENERATED: génère des instantanés de calques à partir des transactions conservées dans le tampon circulaire interne de SurfaceFlinger. La génération d'instantanés de calques se produit lorsque cette source de données est vidée.
  • MODE_DUMP : suit un seul instantané de calques.
  • MODE_GENERATED_BUGREPORT_ONLY : identique à MODE_GENERATED, mais ne déclenche la génération d'instantanés de calques que lorsqu'un rapport de bug est généré, et non chaque fois qu'une trace est vidée.

Indicateurs de trace (trace_flags) :

  • TRACE_FLAG_INPUT: si la surface contient des données d'entrée, suit les spécificités de la fenêtre d'entrée.
  • TRACE_FLAG_COMPOSITION : suit le type de composition et la région visible.

  • TRACE_FLAG_EXTRA: suit les métadonnées de surface supplémentaires, y compris les calques hors écran.

  • TRACE_FLAG_HWC : suit les métadonnées supplémentaires non structurées du compositeur matériel.

  • TRACE_FLAG_BUFFERS: configure SurfaceFlinger pour suivre toutes les modifications de tampon sur la surface. Par défaut, SurfaceFlinger ne suit un nouvel état que lorsque des modifications de géométrie se produisent.

  • TRACE_FLAG_VIRTUAL_DISPLAYS : inclut les calques d'affichage virtuel dans la trace.

Exemple

L'exemple suivant montre le type de trace SurfaceFlinger pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   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
           }
       }
   }
EOF

Pour en savoir plus sur la signification des différentes valeurs de configuration, consultez SurfaceFlinger.

Transitions de l'interface utilisateur

Utilisez le nom de source de données com.android.wm.shell.transition pour ce type de trace.

Options de configuration

Ce type de trace ne comporte aucune option de configuration.

Exemple

L'exemple suivant montre le type de trace de transition de l'interface utilisateur pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger (transactions)

Utilisez le nom de source de données android.surfaceflinger.transactions pour ce type de trace.

Options de configuration

Mode de traçage (mode) : définit la fréquence à laquelle les éléments sont enregistrés :

  • MODE_CONTINUOUS: SurfaceFlinger écrit son tampon circulaire interne de transactions chaque fois que la source de données est vidée. Le tampon circulaire contient l'état initial de SurfaceFlinger et les dernières transactions.

  • MODE_ACTIVE: SurfaceFlinger écrit l'état initial, puis chaque transaction entrante jusqu'à ce que la source de données soit arrêtée.

Exemple

L'exemple suivant montre le type de trace de transactions SurfaceFlinger pour adb.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

Utilisez le nom de source de données android.inputmethod pour ce type de trace.

Options de configuration

Ce type de trace ne comporte aucune option de configuration.

Exemple

L'exemple suivant montre le type de trace IME pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

Utilisez le nom de source de données android.viewcapture pour ce type de trace.

Options de configuration

Ce type de trace ne comporte aucune option de configuration.

Exemple

L'exemple suivant montre le type de trace ViewCapture pour adb :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Exemple complet

Perfetto vous permet de collecter des données provenant de plusieurs sources dans une seule configuration. Vous pouvez collecter toutes les traces Winscope à l'aide d'une seule commande :

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   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
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Capturer des traces dans Android 14 et versions antérieures

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 trace sont disponibles dans /data/misc/wmtrace. Pour copier un fichier ou un répertoire et ses sous-répertoires depuis un appareil, consultez Copier des fichiers vers et depuis un appareil.

Traces WindowManager

Pour capturer des traces WindowManager :

  • Activer la trace :

    adb shell wm tracing start

  • Désactiver la trace :

    adb shell wm tracing stop

  • Enregistrer 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 frame :

    adb shell wm tracing frame

  • Enregistrer chaque transaction :

    adb shell wm tracing transaction

  • Définir la taille maximale du journal (en Ko) :

    adb shell wm tracing size

  • Imprimer l'état de la trace :

    adb shell wm tracing status

  • Définir le niveau de journalisation sur critical (fenêtres visibles uniquement 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

Vider WindowManager

Pour capturer les vidages WindowManager :

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

ProtoLog

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

Dans le processus system_server :

  • Démarrer ProtoLog :

    adb shell cmd window logging start

  • Arrêter ProtoLog :

    adb shell cmd window logging stop

  • Activer ProtoLog pour des groupes de journaux donnés :

    adb shell cmd window logging enable [group...]

  • Désactiver ProtoLog pour des groupes de journaux donnés :

    adb shell cmd window logging disable [group...]

  • Activer la journalisation Logcat pour des groupes de journaux donnés :

    adb shell cmd window logging enable-text [group...]

  • Désactiver la journalisation Logcat pour des groupes de journaux donnés :

    adb shell cmd window logging disable-text [group...]

Dans WMShell :

  • Démarrer ProtoLog :

    adb shell dumpsys activity service SystemUIService WMShell

Traces SurfaceFlinger (calques)

Le traçage des calques SurfaceFlinger utilise la trace Perfetto pour la capture. Pour en savoir plus sur la configuration, consultez la section Configuration de la trace.

L'exemple suivant montre une configuration pour le traçage des calques 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
        }
    }
}

L'exemple de commande suivant génère le traçage des calques SurfaceFlinger :

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

Vider SurfaceFlinger (calques)

Pour capturer les vidages SurfaceFlinger, exécutez la commande suivante :

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

Transitions de l'interface utilisateur

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

Dans le processus system_server, utilisez les commandes suivantes :

  • Démarrer une trace :

    adb shell cmd window shell tracing start

  • Arrêter une trace :

    adb shell cmd window shell tracing stop

  • Démarrer une trace dans WMShell :

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Arrêter une trace dans WMShell :

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Les commandes suivantes sont utilisées pour le traçage de l'éditeur de mode de saisie (IME) :

  1. Démarrer le traçage 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

  • Démarrer le traçage des clients IME, IMS et IMMS :

    adb shell ime tracing stop

SurfaceFlinger (transactions)

Le traçage des transactions SurfaceFlinger utilise la trace Perfetto pour la capture. Pour en savoir plus sur la configuration, consultez la section Configuration de la trace.

L'exemple suivant montre une configuration Perfetto pour le traçage actif de 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

L'exemple suivant montre une configuration Perfetto 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
        }
    }
}

L'exemple de commande suivant génère le traçage des transactions SurfaceFlinger :

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