À partir de 2026, pour nous aligner sur notre modèle de développement stable et garantir la stabilité de la plate-forme pour l'écosystème, nous publierons le code source sur AOSP au deuxième et au quatrième trimestre. Pour créer et contribuer à AOSP, nous vous recommandons d'utiliser android-latest-release au lieu de aosp-main. La branche de fichier manifeste android-latest-release fera toujours référence à la version la plus récente envoyée à AOSP. Pour en savoir plus, consultez Modifications apportées à AOSP.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Déboguer la SDV

Ce guide présente les outils et techniques essentiels pour déboguer les services et les applications qui s'exécutent sur la plate-forme SDV.

Se connecter à l'appareil

L'outil principal pour se connecter à l'appareil et interagir avec lui est Android Debug Bridge (adb). Vérifiez que adb se trouve dans le chemin d'accès de votre système.

Se connecter à l'aide du réseau

Si l'appareil se trouve sur le même réseau et que vous connaissez son adresse IP, vous pouvez vous connecter par Ethernet. Notre système utilise exclusivement les connexions réseau pour adb :

# Connect to the device using its IP address and default port
adb connect <device_ip_address>:5555

Se connecter à plusieurs appareils

Pour gérer plusieurs appareils à partir d'une seule station de travail, vous pouvez vous y connecter via différentes adresses IP. Si vous exécutez plusieurs VM sur un seul hôte, vous devez attribuer des ports différents à chaque appareil. Pour cela, vous devez configurer le démon adb sur chaque appareil SDV afin qu'il écoute sur un port unique, par exemple 5555 pour le premier appareil et 5556 pour le second. Vous pouvez également configurer l'hôte pour qu'il transfère ces ports vers différents invités :

# Connect to the first device
adb connect <device_1_ip_address>:5555

# Connect to a second device
adb connect <device_2_ip_address>:5555

# Connect to a second VM on first device on different port
adb connect <device_1_ip_address>:5556

# List all connected devices to verify
adb devices

Lorsque vous exécutez des commandes adb ultérieures, vous pouvez cibler un appareil spécifique à l'aide de l'option -s avec son adresse complète (ip:port) :

# Run a shell command on the second VM on first device in the above example
adb -s <device_1_ip_address>:5556 shell

Afficher les journaux

Lorsqu'un service échoue ou se comporte de manière inattendue, commencez par consulter les journaux.

Utiliser logcat (journaux Android)

logcat affiche les journaux des services système, des agents et des bundles de services :

# View all logs in real-time
adb logcat

# Filter logs by a specific tag (e.g., the name of your service)
adb logcat -s MyServiceTag

# Filter logs by priority (V: Verbose, D: Debug, I: Info, W: Warn, E: Error, F: Fatal)
# This shows only Error and Fatal messages for a specific tag
adb logcat MyServiceTag:E *:S

# Clear old logs before viewing new ones
adb logcat -c && adb logcat

# Show all logs and return
adb logcat -d

# Color logs by level
adb logcat -v color

# Show timestamps as time since boot
adb logcat -v monotonic

Utiliser dmesg (journaux du noyau)

dmesg affiche les journaux du noyau Linux. Cela est essentiel pour déboguer les éléments suivants :

Problèmes matériels et de pilotes
Paniques du noyau
Refus SELinux (avc: denied) : également affichés dans logcat

# View all kernel messages
adb shell dmesg

# Follow kernel messages in real-time
adb shell dmesg -w

Accéder aux journaux sur Cuttlefish

Lorsque vous exécutez sur un appareil virtuel Cuttlefish, vous pouvez accéder directement aux fichiers journaux à partir du système de fichiers de la machine hôte. Cela est particulièrement utile si adb n'est pas disponible. Lorsque vous démarrez Cuttlefish, il génère tous les chemins de débogage. Vous pouvez également les rechercher à l'aide de cvd fleet pour toutes les instances en cours d'exécution.

Logcat (journaux Android) : cuttlefish/instances/cvd-1/logs/logcat
Journaux du noyau : cuttlefish/instances/cvd-1/logs/kernel.log
Journaux du lanceur Cuttlefish : cuttlefish/instances/cvd-1/logs/launcher.log (utile pour déboguer l'environnement Cuttlefish lui-même)

Vous pouvez utiliser des outils de ligne de commande standards tels que cat, less ou tail -f pour afficher ces fichiers en temps réel.

Interagir avec le shell et le système de fichiers

Obtenez un accès shell pour exécuter des commandes directement sur l'appareil, vérifier l'état des processus et parcourir le système de fichiers :

# Open an interactive shell on the device
adb shell

# From within the shell, you can check running processes
ps -A

# Or check the status of a specific service managed by init
getprop init.svc.<service_name>

Effectuer des opérations sur le système de fichiers

Utilisez adb push et adb pull pour déplacer des fichiers entre votre machine hôte et l'appareil. Utilisez cette fonctionnalité pour déployer des scripts de test, mettre à jour la configuration ou récupérer des vidages sur incident :

# Push a file from your computer to the device
adb push my_local_file.txt /data/local/tmp/

# Pull a file from the device to your computer
adb pull /data/tombstones/tombstone_00 .

Déboguer des applications (C++/Rust)

Vous pouvez déboguer des applications en ligne ou hors connexion.

Utiliser lldb pour le débogage en direct

lldb est le débogueur par défaut dans Android Studio et est souvent préféré pour le développement moderne en C++ et Rust.

Procédez comme suit :

Redémarrez adb pour autoriser les autorisations racine (obligatoires pour le transfert). Utilisez cette commande pour configurer le transfert de port. Sur l'hôte, exécutez :
```
adb root
```
Si un binaire comporte des symboles de débogage, envoyez une version non dépouillée. Vous trouverez la version non dépouillée dans out/target/product/[SDV_FLAVOR]/symbols/[PARTITION]/bin/[EXECUTABLE]. Par exemple, pour importer rpcagent à partir de system_ext et sdv_core_cf, exécutez :
```
adb push out/target/product/sdv_core_cf/symbols/system_ext/bin/rpcagent /data/local/tmp
```
La version non dépouillée se trouve désormais dans /data/local/tmp.
Connectez-vous au client LLDB à l'aide du script pratique lldbclient.py :
```
# Run and connect a binary on device, run on host:
lldbclient.py -r /data/local/tmp/rpcagent

# Connect to an existing process with PID 2759
lldbclient.py -p 2759
```
Ce script connecte lldb à distance. Pour obtenir toutes les options disponibles, exécutez lldbclient.py. Consultez la documentation de votre IDE pour le connecter à lldb.

Analyser les vidages sur incident (tombstones)

Lorsqu'un service plante, un fichier tombstone est généré dans /data/tombstones/. Le fichier contient une trace de la pile, une carte de la mémoire et d'autres informations essentielles.

Extrayez le fichier tombstone, puis utilisez un outil compatible avec les symboles (tel que lldb ou un script dédié) pour l'analyser avec la version non dépouillée du binaire.

Analyser les performances

SDV est compatible avec plusieurs outils de mesure des performances.

Vérifier l'utilisation du processeur et de la mémoire

top : fournit une vue en temps réel des processus en cours d'exécution, triés par utilisation du processeur.
```
adb shell top -m 10  # Show top 10 processes
```
procrank: fournit une répartition détaillée de l'utilisation de la mémoire pour un processus spécifique ou pour l'ensemble du système.
```
adb shell procrank
```

Utiliser dumpsys pour l'état du service

dumpsys est un outil puissant permettant d'interroger l'état interne de n'importe quel service système Android.

# List all available services
adb shell dumpsys -l

# Dump the state of a specific service or agent
adb shell dumpsys <service_name>

Utiliser torq pour l'analyse des performances

torq est un outil de ligne de commande qui simplifie les tâches de profilage et de traçage sur Android. Il permet d'exécuter Simpleperf, Perfetto et d'autres tâches classiques lors de l'analyse des performances du système.

Utiliser Perfetto pour le traçage

Perfetto est l'outil standard de traçage à l'échelle du système sur Android. Perfetto vous permet d'enregistrer des événements système, des points de trace au niveau de l'application et des compteurs de performances, et de les visualiser sur une chronologie.

Étapes clés :

Ajoutez des points de trace dans votre code C++ ou Rust :
- C++ : utilisez le SDK Perfetto avec les macros TRACE_EVENT.
- Rust : utilisez le crate tracing, qui émet des événements ATrace compatibles avec Perfetto.
Créez un fichier de configuration textproto pour spécifier les sources de données (par exemple, ftrace, track_event), les catégories et les tags.
Utilisez le record_android_trace script (external/perfetto/tools/record_android_trace) avec votre fichier de configuration pour capturer la trace de l'appareil.
Ouvrez le fichier de suivi généré dans l'interface utilisateur Web de Perfetto pour analyser le comportement du système , identifier les goulots d'étranglement et comprendre les interactions entre les services.

Pour obtenir des instructions détaillées sur l'instrumentation, la configuration et la collecte, consultez Utiliser le traçage pour obtenir des insights sur les performances du système.

Utiliser Simpleperf pour le profilage

Simpleperf est un outil de ligne de commande polyvalent pour le profilage des performances sur Android, semblable à Linux perf.

Cas d'utilisation courants :

Profilage du processeur : identifiez les fonctions qui consomment le plus de temps CPU.
Analyse hors processeur : analysez pourquoi les threads sont en veille ou bloqués.
Compteurs matériels : accédez aux compteurs de performances matérielles.

Exemples de commandes :

# Go to simpleperf scripts
cd system/extras/simpleperf/scripts

# Profile system for 20 seconds and record call graph
./app_profiler.py --system_wide -r "--call-graph fp --duration 20"

# Record a profile for a specific process (PID 1)
./app_profiler.py --pid 1 -r "--call-graph fp --duration 5"

# Pull the profile data
adb pull /data/local/tmp/perf.data .

# Generate a report with symbol resolution
./report_html.py --add_source_code --source_dirs $ANDROID_BUILD_TOP --add_disassembly -o report.html

Simpleperf propose de nombreux autres événements et options. Pour obtenir une documentation complète, consultez le guide Simpleperf.

Refus SELinux

Symptôme : votre service ne démarre pas, n'accède pas à un fichier ou n'utilise pas une fonctionnalité, et vous voyez un message avc: denied dans dmesg ou logcat.

[ 123.456] avc: denied { read } for pid=789 comm="my_service" name="some_file" dev="sda1" ino=123 scontext=u:r:my_service_t:s0 tcontext=u:object_r:some_file_t:s0 tclass=file permissive=0

Débogage rapide (pour le développement uniquement)

Vous pouvez désactiver temporairement l'application forcée de SELinux pour voir si le problème est résolu. Cela confirme que le problème est dû à une règle de stratégie SELinux manquante.

# Disabling SELinux requires root permission
adb root

# Set SELinux to permissive mode
adb shell setenforce 0

# Check the current mode (should return "Permissive")
adb shell getenforce

Solution : l'outil audit2allow de l'arborescence source Android sur le message de refus. Cela génère la règle de stratégie .te correcte à ajouter à la configuration SELinux de votre appareil.