Outil de ligne de commande Logcat

Stay organized with collections Save and categorize content based on your preferences.

Logcat est un outil de ligne de commande qui vide un journal des messages système, y compris les traces de la pile enregistrées lorsque l'appareil génère une erreur et 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 Écrire et afficher 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. Les plus pertinents sont les suivants : main, qui stocke la plupart des journaux d'application, system, qui stocke les messages provenant de l'OS Android, et crash, qui stocke les journaux de plantages. Chaque entrée de journal est associée à une priorité (VERBOSE, DEBUG, INFO, WARNING, ERROR ou FATAL), à une balise qui identifie l'origine du journal et au message de journal lui-même.

L'interface 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 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 :

  1. Filtrage du 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.
  2. Filtrage des 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) :
    • log.tag.MyApp
    • persist.log.tag.MyApp
    • log.tag
    • persist.log.tag
  3. Filtrage des applications : 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.
  4. 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, reportez-vous aux informations ci-dessous.

Syntaxe de la ligne de commande

Pour exécuter logcat via l'interface système adb, l'utilisation générale est la suivante :

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

Vous pouvez exécuter logcat en tant que commande adb ou directement dans une invite d'interface système de votre émulateur ou de votre appareil connecté. Pour afficher la sortie du journal à l'aide d'adb, accédez au répertoire platform-tools/ du SDK et exécutez :

adb logcat

Pour accéder à l'aide en ligne de logcat, démarrez un appareil, puis exécutez :

adb logcat --help

Vous pouvez créer une connexion shell à un appareil et exécuter :

$ adb shell
# logcat

Options

Le tableau suivant décrit les options de ligne de commande pour logcat.

Option Description
-b <buffer> Charge un autre tampon de journal pour l'affichage, comme events ou radio. Les tampons main, system et crash sont utilisés par défaut. Consultez la section Afficher d'autres tampons de journal.
-c, --clear Efface (vide) les tampons sélectionnés et quitte la fonction. Le tampon par défaut est main, system et crash. Pour effacer tous les tampons, utilisez -b all -c.
-e <expr>, --regex=<expr> Affiche uniquement les lignes dont le message de journal correspond à <expr>, où <expr> est une expression régulière.
-m <count>, --max-count=<count> Quitte la fonction après avoir imprimé un certain nombre de lignes (<count>). Cette option est destinée à être associée à --regex, mais fonctionne de manière autonome.
--print Associée à --regex et --max-count pour permettre au contenu de contourner le filtre d'expression régulière, mais s'arrête toujours lorsque le bon nombre de correspondances est atteint.
-d Vide le journal sur l'écran et quitte la fonction.
-f <filename> Écrit la sortie du message de journal dans <filename>. La valeur par défaut est stdout.
-g, --buffer-size Imprime la taille du tampon de journal et des sorties spécifiés.
-n <count> Définit le nombre maximal de journaux alternés sur <count>. La valeur par défaut est 4. Nécessite l'option -r.
-r <kbytes> Alterne le fichier journal selon un intervalle de <kbytes> pour la sortie. La valeur par défaut est 16. Nécessite l'option -f.
-s Équivaut à l'expression de filtre '*:S', qui définit la priorité de toutes les balises sur "silencieux" et qui est utilisée pour précéder une liste d'expressions de filtre qui ajoutent du contenu. Pour en savoir plus, consultez la section sur le filtrage de la sortie dee journaux.
-v <format> Définissez le format de sortie des messages de journal. La valeur par défaut est threadtime. Pour obtenir la liste des formats acceptés, consultez la section Contrôler le format de sortie d'un journal.
-D, --dividers Imprime des séparateurs entre chaque tampon de journal.
-c Vide (efface) la totalité du journal et quitte la fonction.
-t <count> Imprime uniquement le nombre de lignes le plus récent. Cette option inclut la fonctionnalité -d.
-t '<time>' Imprime les lignes les plus récentes depuis l'heure spécifiée. Cette option inclut la fonctionnalité -d. Pour plus d'informations sur les paramètres d'ajout de guillemets avec les espaces de représentation vectorielle, consultez l'option -P.

adb logcat -t '01-26 20:52:41.820'
-T <count> Imprime le nombre de lignes le plus récent depuis le moment spécifié. Cette option n'inclut pas la fonctionnalité -d.
-T '<time>' Imprime les lignes les plus récentes depuis l'heure spécifiée. Cette option n'inclut pas la fonctionnalité -d. Pour plus d'informations sur les paramètres d'ajout de guillemets avec les espaces de représentation vectorielle, consultez l'option -P.

adb logcat -t '01-26 20:52:41.820'
-L, --last Vide les journaux avant le dernier redémarrage.
-B, --binary Génère le journal dans le binaire.
-S, --statistics Inclut les statistiques dans la sortie pour vous aider à identifier et à cibler les spammeurs de journaux.
-G <size> Définit la taille du tampon en anneau du journal. Vous pouvez ajouter K ou M à la fin pour indiquer des kilooctets ou des mégaoctets.
-p, --prune Imprime (lit) la liste d'autorisation et la liste de blocage et n'accepte aucun argument, comme suit :

adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<allowlist_and_denylist>'
Écrit (définit) la liste d'autorisation et la liste de blocage afin d'ajuster le contenu de journalisation à une fin spécifique. Vous fournissez un contenu mixte contenant des entrées issues de la liste d'autorisation et de la liste de blocage, où <allowlist> ou <denylist> peuvent correspondre à un UID, un UID/PID ou un PID. À l'aide des statistiques logcat (logcat -S), vous pouvez envisager d'ajuster la liste d'autorisation et la liste de blocage à diverses fins :
  • Accorder une durée de vie maximale à des contenus de journalisation spécifiques grâce aux sélections d'UID
  • Empêcher une personne (UID) ou quelque chose (PID) de consommer ces ressources afin d'augmenter la durée de vie du journal et d'avoir ainsi une meilleure visibilité des problèmes que vous diagnostiquez

Par défaut, le système de journalisation empêche automatiquement le pire contrevenant dans les statistiques de journal de manière dynamique afin de faire de la place pour les nouveaux messages de journal. Une fois qu'il a épuisé l'heuristique, le système élimine les entrées les plus anciennes pour faire de la place aux nouveaux messages.

En ajoutant une liste d'autorisation, vous empêchez votre numéro d'identification Android (AID), qui devient l'AID et le GID des processus, d'être déclaré comme un contrevenant. De plus, l'ajout d'une liste de blocage permet de libérer de l'espace avant que les pires contrevenants ne soient pris en compte. Vous pouvez choisir l'intensité de l'élagage et désactiver cette option pour ne supprimer que le contenu des entrées les plus anciennes dans chaque tampon de journal.

Guillemets

adb logcat ne conserve pas les guillemets. Par conséquent, la syntaxe permettant de spécifier une liste d'autorisation et une liste de blocage est la suivante :


$ adb logcat -P '"<allowlist_and_denylist>"'

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

L'exemple suivant spécifie une liste d'autorisation avec PID 32676 et UID 675, ainsi qu'une liste de blocage avec PID 32677 et UID 897. PID 32677 dans la liste de blocage est pondéré afin d'accélérer l'élagage.


adb logcat -P '"/32676 675 ~/32677 897"'

Vous pouvez utiliser d'autres variantes de commande pour les listes d'autorisation et de blocage :


~! worst uid denylist
~1000/! worst pid in system (1000)
--pid=<pid> ... Imprime uniquement les journaux issus du PID donné.
--wrap Se met en veille pendant deux heures ou lorsque le tampon est sur le point d'encapsuler le premier élément. Améliore l'efficacité de l'interrogation en fournissant un processus wakeup qui enchaîne le processus.

Filtrer les résultats 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 (par exemple, "Affichage" pour le système d'affichage).
  • 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 tous les messages de journal 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 est un excellent moyen de vous assurer que la sortie du journal est limitée aux filtres que vous avez explicitement spécifiés. Elle permet à vos filtres de servir de liste d'autorisation pour la sortie du journal.

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 à partir de votre ordinateur de développement (au lieu de l'exécuter sur une interface système adb à distance), 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"

Notez que le filtre ANDROID_LOG_TAGS n'est pas exporté vers l'émulateur/l'instance d'appareil si vous exécutez logcat à partir d'une interface système distante 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 répertoriés ci-dessous.

  • 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

Notez que vous ne pouvez spécifier qu'un seul format de sortie avec l'option -v, mais vous pouvez définir autant de modificateurs que vous le souhaitez. Logcat ignorera les modificateurs qui n'ont pas d'intérêt.

Modificateurs de format

Les modificateurs de format permettent de modifier la sortie logcat en combinant un ou plusieurs des modificateurs suivants. 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 et time.

Pour obtenir les détails du modificateur de format, saisissez logcat -v --help sur 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 : durée d'affichage en secondes à partir du 1er janvier 1970.
  • monotonic : durée d'affichage en secondes de processeur à partir du dernier démarrage.
  • printable : vérifiez que tout le contenu de la journalisation binaire est échappé.
  • uid : si les contrôles d'accès le permettent, affichez l'UID ou l'ID Android du processus journalisé.
  • usec : affiche l'heure avec une précision de l'ordre de la microseconde.
  • 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, vous pouvez exécuter 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 : affichez le tampon contenant les messages radio/téléphoniques.
  • events : affichez les messages interprétés du tampon d'événements du système binaire.
  • main : affichez le tampon de journal principal (par défaut). Ne contient pas les messages de journal du système et des plantages.
  • system : affichez le tampon du journal système (par défaut).
  • crash : affichez le tampon du journal des plantages (par défaut).
  • all : affichez tous les tampons.
  • default : affichez 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

Vous pouvez également spécifier plusieurs options -b pour tous les tampons que vous souhaitez imprimer, comme suit :

logcat -b main -b radio -b events

Vous pouvez spécifier un seul indicateur -b avec une liste de tampons séparés par une virgule, par exemple :

logcat -b main,radio,events

Journalisation à 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 :

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);

Voici ce à quoi ressemble la sortie logcat :

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