Capturer une trace système via la ligne de commande

La commande systrace appelle l'outil Systrace, qui vous permet de collecter et d'inspecter les informations de synchronisation sur tous les processus en cours d'exécution sur votre appareil au niveau du système.

Ce document explique comment générer des rapports Systrace à partir de la ligne de commande. Sur les appareils équipés d'Android 9 (niveau d'API 28) ou version ultérieure, vous pouvez également générer des rapports Systrace à l'aide de l'application système Traçage système.

Pour exécuter systrace, procédez comme suit :

  1. Dans Android Studio, téléchargez et installez la dernière version de SDK Tools pour Android.
  2. Installez Python et incluez-le dans la variable d'environnement PATH de votre station de travail.
  3. Ajoutez android-sdk/platform-tools/ à votre variable d'environnement PATH. Ce répertoire contient le binaire Android Debug Bridge (adb), appelé par le programme systrace.
  4. Connectez un appareil exécutant Android 4.3 (niveau d'API 18) ou version ultérieure à votre système de développement à l'aide d'une connexion de débogage USB.

La commande systrace est fournie dans le package SDK Tools pour Android et se trouve dans android-sdk/platform-tools/systrace/.

Syntaxe

Pour générer le rapport HTML d'une application, vous devez exécuter systrace à partir de la ligne de commande en utilisant la syntaxe suivante :

python systrace.py [options] [categories]

Par exemple, la commande suivante appelle systrace pour enregistrer l'activité de l'appareil et générer un rapport HTML nommé mynewtrace.html. Cette liste de catégories est une liste par défaut raisonnable pour la plupart des appareils.

$ python systrace.py -o mynewtrace.html sched freq idle am wm gfx view \
    binder_driver hal dalvik camera input res memory

Conseil : Si vous souhaitez afficher les noms des tâches dans la sortie de trace, vous devez inclure la catégorie sched dans vos paramètres de commande.

Pour afficher la liste des catégories compatibles avec votre appareil connecté, exécutez la commande suivante :

$ python systrace.py --list-categories

Si vous ne spécifiez aucune catégorie ou option, systrace génère un rapport qui inclut toutes les catégories disponibles et utilise les paramètres par défaut. Les catégories disponibles dépendent de l'appareil connecté que vous utilisez.

Options générales

Options générales Description
-h | --help Affiche le message d'aide.
-l | --list-categories Recense les catégories de traçage disponibles pour votre appareil connecté.

Commandes et options de commande

Commandes et options Description
-o file Écrit le rapport de trace HTML dans le file spécifié. Si vous ne précisez pas cette option, systrace enregistre votre rapport dans le même répertoire que systrace.py et le nomme trace.html.
-t N | --time=N Trace l'activité de l'appareil pendant N secondes. Si vous ne spécifiez pas cette option, systrace vous invite à mettre fin à la trace en appuyant sur la touche Entrée depuis la ligne de commande.
-b N | --buf-size=N Utilise une taille de tampon de trace de N kilo-octets. Cette option vous permet de limiter la taille totale des données collectées lors d'une trace.
-k functions
| --ktrace=functions		 Trace l'activité de fonctions spécifiques du noyau en les spécifiant dans une liste d'éléments séparés par une virgule.
-a app-name
| --app=app-name		 Active le traçage des applications, spécifié sous la forme d'une liste de noms de processus séparés par une virgule. Les applications doivent contenir des appels d'instrumentation de traçage provenant de la classe Trace. Vous devez spécifier cette option chaque fois que vous profilez votre application. De nombreuses bibliothèques, telles que RecyclerView, incluent des appels d'instrumentation de traçage qui fournissent des informations utiles lorsque vous activez le traçage au niveau de l'application. Pour en savoir plus, consultez Définir des événements personnalisés.

Pour tracer toutes les applications sur un appareil équipé d'Android 9 (niveau d'API 28) ou version ultérieure, transmettez le caractère générique "*", y compris les guillemets.

--from-file=file-path Crée un rapport HTML interactif à partir d'un fichier, par exemple un TXT contenant des données de trace brutes, au lieu d'exécuter une trace en direct.
-e device-serial
| --serial=device-serial		 Récupère la trace d'un appareil connecté spécifique, identifié par son numéro de série.
categories Inclut des informations de traçage pour les processus système que vous spécifiez, par exemple gfx pour les processus système qui affichent des graphiques. Vous pouvez exécuter systrace avec la commande -l pour afficher la liste des services disponibles pour votre appareil connecté.