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

Outil de ligne de commande Logcat

Logcat est un outil de ligne de commande qui vide un journal de messages système, y compris les messages que vous avez écrits à partir de votre application avec la classe Log.

Cette page se concentre sur l'outil de ligne de commande logcat, mais vous pouvez également afficher les messages de journal à partir de la fenêtre Logcat d'Android Studio. Pour en savoir plus sur l'affichage et le filtrage des journaux à partir d'Android Studio, consultez la section Afficher et écrire des journaux avec Logcat.

Présentation du système de journalisation

Le système de journalisation Android est un ensemble de tampons circulaires structurés gérés par le processus système logd. Cet ensemble est fixe et défini par le système. Voici les tampons les plus pertinents :

main, qui stocke la plupart des journaux d'application.
system, qui stocke les messages provenant de l'OS Android.
crash, qui stocke les journaux de plantage. Chaque entrée de journal est associée à une priorité, à une balise qui identifie l'origine du journal et au message de journal lui-même.

L'interface C/C++ principale du système de journalisation est la bibliothèque partagée liblog et son en-tête <android/log.h>. Tous les mécanismes de journalisation spécifiques à un langage (y compris android.util.Log) finissent par appeler la fonction __android_log_write. Par défaut, la fonction __android_log_logd_logger est appelée, laquelle envoie l'entrée de journal à logd à l'aide d'un socket. À partir du niveau d'API 30, la fonction de journalisation peut être modifiée en appelant __android_set_log_writer. Pour en savoir plus, consultez la documentation du NDK.

Les journaux affichés par adb logcat sont soumis à quatre niveaux de filtrage :

Filtrage par temps de compilation: En fonction des paramètres de compilation, certains journaux peuvent être complètement supprimés du binaire. Par exemple, ProGuard peut être configuré pour supprimer les appels à Log.d du code Java.
Filtrage par propriétés système: liblog interroge un ensemble de propriétés système pour déterminer le niveau de gravité minimal à envoyer à logd. Si vos journaux comportent la balise MyApp, les propriétés suivantes sont vérifiées et doivent contenir la première lettre correspondant à la gravité minimale (V, D, I, W, E ou S pour désactiver tous les journaux) :
Filtrage par application: Si aucune des propriétés n'est définie, liblog utilise la priorité minimale définie par __android_log_set_minimum_priority. Le paramètre par défaut est INFO.
Filtrage de l'affichage: adb logcat accepte des filtres supplémentaires qui peuvent réduire la quantité de journaux affichés à partir de logd. Pour en savoir plus, consultez la section sur le filtrage de la sortie des journaux.

Syntaxe de la ligne de commande

Pour exécuter logcat via le shell adb, l'utilisation générale est la suivante :

[adb] shell logcat [<option>] ... [<filter-spec>] ...

Il existe également un raccourci pour adb logcat, mais il se développe simplement en adb shell logcat.

Options

logcat propose de nombreuses options. Les options disponibles dépendent de la version du système d'exploitation de l'appareil que vous utilisez. Pour afficher l'aide concernant logcat spécifique à l'appareil que vous utilisez, exécutez la commande suivante :

    adb logcat --help

Notez que, comme logcat est un outil destiné aussi bien aux développeurs d'OS qu'aux développeurs d'applications (les développeurs d'applications étant censés utiliser Android Studio à la place), de nombreuses options ne sont utilisables qu'en tant que root.

Filtrer la sortie d'un journal

La balise d'un message de journal système est une chaîne courte indiquant le composant système d'où provient le message ("View" pour le système d'affichage, par exemple).

La priorité correspond à l'une des valeurs associées à l'un des caractères suivants, classées de la priorité la plus basse à la plus élevée :

V : détaillé (priorité la plus faible)
D : débogage
I : information
W : avertissement
E : erreur
F : fatal
S : silencieux (priorité la plus élevée, avec laquelle rien n'est imprimé)

Pour obtenir la liste des balises utilisées dans le système, avec les priorités, exécutez logcat et observez les deux premières colonnes de chaque message, qui se présentent sous la forme <priority>/<tag>.

Voici un exemple de sortie logcat courte obtenue avec la commande logcat -v brief output. Elle indique que le message concerne le niveau de priorité "I" et la balise "ActivityManager" :

I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}

Pour réduire la sortie du journal à un niveau gérable, vous pouvez utiliser des expressions de filtre. Les expressions de filtre vous permettent d'indiquer au système les combinaisons de balises et de priorités qui vous intéressent. Le système masque les autres messages en fonction des balises spécifiées.

Une expression de filtre suit le format tag:priority ..., où tag indique la balise qui vous intéresse et priority indique le niveau de priorité minimal à signaler pour cette balise. Les messages associés à cette balise, à un niveau de priorité supérieur ou égal au niveau spécifié, sont écrits dans le journal. Vous pouvez fournir un nombre illimité de spécifications tag:priority dans une seule expression de filtre. La série de spécifications est délimitée par des espaces blancs.

Voici un exemple d'expression de filtre qui masque tous les messages de journal, à l'exception de ceux associés à la balise "ActivityManager", au niveau de priorité "Information" ou à un niveau supérieur, et ceux associés à la balise "MyApp", avec la priorité "Débogage" ou une priorité supérieure :

adb logcat ActivityManager:I MyApp:D *:S

Le dernier élément de l'expression ci-dessus, *:S, définit le niveau de priorité de toutes les balises sur "silencieux". Ainsi, seuls les messages de journal contenant "ActivityManager" et "MyApp" sont affichés. L'utilisation de *:S permet de s'assurer que la sortie du journal sera limitée aux filtres que vous avez explicitement spécifiés. *:S permet à vos filtres de servir de liste d'autorisation pour la sortie du journal.

Remarque : Dans certains shells, le caractère "*" est réservé par le shell. Si vous utilisez un shell de ce type, placez l'expression de filtre entre guillemets : adb logcat "ActivityManager:I MyApp:D *:S"

L'expression de filtre suivante affiche tous les messages de journal associés au niveau de priorité "avertissement" ou à un niveau supérieur, au niveau de l'ensemble des balises :

adb logcat *:W

Si vous exécutez logcat depuis votre ordinateur de développement et pas sur un shell adb distant, vous pouvez également définir une expression de filtre par défaut en exportant une valeur pour la variable d'environnement ANDROID_LOG_TAGS :

export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

Le filtre ANDROID_LOG_TAGS n'est pas exporté vers l'émulateur/l'instance d'appareil si vous exécutez logcat à partir d'un shell distant ou si vous utilisez adb shell logcat.

Contrôler le format de sortie d'un journal

Les messages de journal contiennent plusieurs champs de métadonnées, en plus de la balise et de la priorité. Vous pouvez modifier le format de sortie des messages pour qu'ils affichent un champ de métadonnées spécifique. Pour ce faire, utilisez l'option -v et spécifiez l'un des formats de sortie compatibles suivants :

brief : affiche la priorité, la balise et le PID du processus émettant le message.
long : affiche tous les champs de métadonnées et les messages séparés avec des lignes vides.
process : affiche uniquement le PID.
raw : affiche le message de journal brut sans aucun autre champ de métadonnées.
tag : affiche uniquement la priorité et la balise.
thread: : ancien format indiquant la priorité, le PID et le TID du thread émettant le message.
threadtime (par défaut) : affiche la date, l'heure d'appel, la priorité, la balise, le PID et le TID du thread émettant le message.
time : affiche la date, l'heure d'appel, la priorité, la balise et le PID du processus émettant le message.

Lorsque vous démarrez logcat, vous pouvez spécifier le format de sortie souhaité à l'aide de l'option -v :

[adb] logcat [-v <format>]

Voici un exemple de génération de messages au format de sortie thread :

adb logcat -v thread

Vous ne pouvez spécifier qu'un seul format de sortie avec l'option -v. Vous pouvez cependant définir autant de modificateurs que vous le souhaitez, s'ils sont pertinents. logcat ignore les modificateurs non pertinents.

Modificateurs de format

Les modificateurs de format modifient la sortie de logcat. Pour spécifier un modificateur de format, utilisez l'option -v, comme suit :

adb logcat -b all -v color -d

Chaque message de journal Android est associé à une balise et à une priorité. Vous pouvez combiner n'importe quel modificateur de format avec l'une des options de format suivantes :

brief
long
process
raw
tag
thread
threadtime
time

Pour mettre en forme les détails de modificateur suivants, saisissez logcat -v --help dans la ligne de commande :

color : affiche chaque niveau de priorité avec une couleur différente.
descriptive : affiche la description des événements de tampon de journal. Ce modificateur ne concerne que les messages du tampon de journal d'événements et n'a aucun effet sur les autres tampons non binaires. Les descriptions d'événements proviennent de la base de données des journaux d'événements.
epoch : affiche l'heure en secondes à partir du 1er janvier 1970.
monotonic : affiche l'heure en secondes CPU à partir du dernier démarrage.
printable : vérifie que tout le contenu de la journalisation binaire est échappé.
uid : si les contrôles d'accès le permettent, affiche l'UID ou l'ID Android du processus journalisé.
usec : affiche l'heure à la microseconde près.
UTC : affiche l'heure au format UTC.
year : ajoute l'année à l'heure affichée.
zone : ajoute le fuseau horaire local à l'heure affichée.

Afficher d'autres tampons de journal

Le système de journalisation Android conserve plusieurs tampons circulaires pour les messages de journal, qui ne sont pas tous envoyés au tampon circulaire par défaut. Pour afficher des messages de journal supplémentaires, exécutez la commande logcat avec l'option -b afin de demander l'affichage d'un autre tampon circulaire. Vous pouvez afficher les autres tampons suivants :

radio : affiche le tampon contenant les messages radio/téléphoniques.
events : affiche les messages interprétés du tampon d'événements du système binaire.
main : affiche le tampon du journal principal (par défaut), qui ne contient pas les messages du journal des plantages ni les messages du journal système.
system : affiche le tampon du journal système (par défaut).
crash : affiche le tampon du journal des plantages (par défaut).
all : affiche tous les tampons.
default : afficher les tampons main, system et crash.

L'option -b s'utilise comme suit :

[adb] logcat [-b <buffer>]

Voici un exemple d'affichage d'un tampon de journal contenant des messages radio et téléphoniques :

adb logcat -b radio

Si vous souhaitez spécifier plusieurs indicateurs -b pour tous les tampons à imprimer, saisissez la commande suivante :

logcat -b main -b radio -b events

Spécifiez un seul indicateur -b avec une liste de tampons séparés par une virgule, par exemple :

logcat -b main,radio,events

Créer des entrées de journal à partir du code

La classe Log vous permet de créer dans le code des entrées de journal qui s'affichent dans l'outil logcat. Voici les méthodes de journalisation courantes :

Log.v(String, String) (détaillé)
Log.d(String, String) (débogage)
Log.i(String, String) (information)
Log.w(String, String) (avertissement)
Log.e(String, String) (erreur)

Par exemple, si vous utilisez l'appel suivant :

Kotlin

Log.i("MyActivity", "MyClass.getView() — get item number $position")

Java

Log.i("MyActivity", "MyClass.getView() — get item number " + position);

logcat génère un résultat semblable à :

I/MyActivity( 1557): MyClass.getView() — get item number 1