Capturer des traces avec des commandes adb

Vous pouvez collecter des traces Winscope à l'aide de la ligne de commande adb sur les versions de débogage (c'est-à-dire les versions userdebug et eng). Avant de collecter les 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 les 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 Capturer des traces dans Android 14 et versions antérieures.

WindowManager

Utilisez le nom de la 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 un impact minimal sur les performances.

  • Fréquence des journaux (log_frequency) : définit la fréquence à laquelle les éléments sont consigné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 unique 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 la source de données android.protolog pour ce type de trace.

Options de configuration

Mode Trace (tracing_mode) : détermine la configuration du journal à utiliser :

  • DEFAULT : n'enregistre que les groupes et les niveaux de journaux spécifiés dans group_overrides.
  • ENABLE_ALL : suit tous les groupes et niveaux de journaux, 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 tracé, sauf si un remplacement de groupe est spécifié. Par exemple, cela permet d'enregistrer tous les avertissements et toutes les 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

Remplacements de groupe (group_overrides) : permet de configurer manuellement le niveau de journalisation pour chaque groupe ProtoLog. Chaque groupe contient :

  • 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 la valeur est définie sur true, collecte la trace de pile pour chaque message ProtoLog du groupe en cours de traçage.

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 la source de données android.input.inputevent pour ce type de trace.

Options de configuration

Mode Trace (trace_mode) : détermine si la trace d'entrée doit être démarrée à l'aide de règles respectueuses de 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 à tracer. Pour en savoir plus sur la spécification des règles de la trace, consultez android_input_event_config.proto.

Exemple

Voici un exemple de 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 la source de données android.surfaceflinger.layers pour ce type de trace.

Options de configuration

Mode Trace (mode) : définit la fréquence à laquelle les éléments sont consigné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 du calque a lieu lorsque cette source de données est vidée.
  • MODE_DUMP : trace un instantané d'une seule couche.
  • MODE_GENERATED_BUGREPORT_ONLY : identique à MODE_GENERATED, mais déclenche la génération d'instantanés de calques uniquement lorsqu'un rapport de bug est créé, 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 non structurées supplémentaires du compositeur matériel.

  • TRACE_FLAG_BUFFERS : configure SurfaceFlinger pour qu'il trace 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 couches 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 Shell

Utilisez le nom de la 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 du shell 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 la source de données android.surfaceflinger.transactions pour ce type de trace.

Options de configuration

Mode Trace (mode) : définit la fréquence à laquelle les éléments sont consigné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 des 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 la 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 la 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 ou version antérieure

Exécutez adb root avant d'exécuter les commandes adb shell pour chacune des traces suivantes. À la fin du traçage, 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 les traces WindowManager :

  • Activer le traçage :

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

    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 (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

Dumps WindowManager

Pour capturer les dumps 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

  • Activez ProtoLog pour les groupes de journaux concernés :

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

  • Désactiver ProtoLog pour des groupes de journaux spécifiques :

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

  • Activez la journalisation Logcat pour les groupes de journaux spécifiés :

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

  • Désactivez la journalisation Logcat pour les 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 couches SurfaceFlinger utilise la trace Perfetto pour la capture. Pour en savoir plus sur la configuration, consultez Configuration du traçage.

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

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 \

Dumps SurfaceFlinger (calques)

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

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

Transitions Shell

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

Dans le processus system_server, utilisez les commandes suivantes :

  • Démarrez 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ê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 méthode d'entrée (IME) :

  1. Démarrez 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

  • Commencez à tracer les 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 Configuration du traçage.

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 \