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

Capturer des traces avec des commandes adb

Les traces Winscope peuvent être collectées avec 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.

Sous Android 14 et versions antérieures, chaque trace Winscope dispose d'une commande différente et vous pouvez les collecter 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 le niveau de verbosité du journal. Valeurs acceptées:
- LOG_LEVEL_VERBOSE: consigne tous les éléments avec la quantité maximale d'informations.
- LOG_LEVEL_DEBUG: consigne tous les éléments, mais n'écrit pas toutes les données de configuration.
- LOG_LEVEL_CRITICAL: n'enregistre que 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 journalisés:
- LOG_FREQUENCY_FRAME: permet de tracer les instantanés d'état lorsqu'un frame est validé.
- LOG_FREQUENCY_TRANSACTION: permet de suivre les instantanés d'état chaque fois qu'une transaction est validée.
- LOG_FREQUENCY_SINGLE_DUMP: permet de tracer des 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

Voici un exemple de 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 de traçage (tracing_mode): détermine la configuration de journalisation à utiliser:

DEFAULT: ne trace que les groupes et niveaux de journal spécifiés dans group_overrides.
ENABLE_ALL: permet de tracer tous les groupes et niveaux de journaux, sauf si spécifié dans group_overrides.

Niveau de journalisation minimal (default_log_from_level): si défini, tout message dont le niveau de journalisation est supérieur ou égal à ce niveau est tracé, sauf si un forçage de groupe est spécifié. Par exemple, cela permet d'enregistrer tous les avertissements et 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

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

Avertissement :La journalisation des traces de pile est lente et affecte les performances de l'appareil. Cette fonctionnalité est plus adaptée au développement local.

Exemple

Voici un exemple de 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 de suivi (trace_mode): détermine si la trace d'entrée doit être démarrée à l'aide de règles de protection de la confidentialité ou si elle doit 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 de traçage (mode): définit la fréquence à laquelle les éléments sont consignés:

MODE_ACTIVE: trace les instantanés des calques. Un instantané est créé chaque fois qu'une modification de calque se produit.
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 des instantanés de la couche se produit lorsque cette source de données est effacée.
MODE_DUMP: trace un instantané d'une seule couche.
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 créé, et non chaque fois qu'une trace est effacée.

Flags 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: trace le type de composition et la région visible.
TRACE_FLAG_EXTRA: trace des métadonnées de surface supplémentaires, y compris des calques hors écran.

Avertissement :Ce champ est très descriptif et nécessite une grande quantité de mémoire.
TRACE_FLAG_HWC: permet de suivre les métadonnées de compilateur matériel non structurées supplémentaires.

Avertissement :Ce champ est très descriptif et nécessite une grande quantité de mémoire.
TRACE_FLAG_BUFFERS: configure SurfaceFlinger pour tracer toutes les modifications de tampon sur la surface. Par défaut, SurfaceFlinger ne trace un nouvel état que lorsque des modifications de géométrie se produisent.
TRACE_FLAG_VIRTUAL_DISPLAYS: inclut les calques d'affichage virtuels dans la trace.

Exemple

Voici un exemple de 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 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

Voici un exemple de type de trace de transition de 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 de traçage (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 effacée. La mémoire tampon en anneau contient l'état initial de SurfaceFlinger et les dernières transactions.
MODE_ACTIVE: SurfaceFlinger écrit l'état initial, puis chaque transaction entrante jusqu'à l'arrêt de la source de données.

Exemple

Voici un exemple de type de trace de transaction 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

Voici un exemple de 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

Voici un exemple de 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 sur 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 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 depuis un appareil, consultez la section Copier des fichiers vers et depuis un appareil.

Traces WindowManager

Pour capturer des traces WindowManager:

Activez le traçage:
```
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
```
Enregistrer la trace une fois par frame:
```
adb shell wm tracing frame
```
Journalisez chaque transaction:
```
adb shell wm tracing transaction
```
Définissez la taille maximale des journaux (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
```

Vidages WindowManager

Pour capturer des 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
```
Activez ProtoLog pour les groupes de journaux donnés:
```
adb shell cmd window logging enable [group...]
```
Désactivez ProtoLog pour les 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 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 (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 section 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 pour générer un traçage pour les calques SurfaceFlinger:

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

Vidages SurfaceFlinger (calques)

Pour capturer des vidages SurfaceFlinger:

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

Transitions de shell

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

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ê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) :

Démarrez le traçage IME pour les clients de mode de saisie (IM), le service de mode de saisie (IMS) et le service de gestion du mode de saisie (IMMS):
```
adb shell ime tracing start
```
Démarrez 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 traçabilité.

Consultez l'exemple de configuration Perfetto suivant pour le suivi 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

Consultez l'exemple de configuration Perfetto suivant 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 un traçage des transactions SurfaceFlinger:

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