Logcat-Befehlszeilentool

Logcat ist ein Befehlszeilentool, das ein Log von Systemmeldungen ausgibt, einschließlich der Nachrichten, die Sie aus der Anwendung mit der Klasse Log geschrieben haben.

Auf dieser Seite geht es um das logcat-Befehlszeilentool. Sie können aber auch Logeinträge aus dem Fenster Logcat in Android Studio aufrufen. Informationen zum Ansehen und Filtern von Logs aus Android Studio finden Sie unter Logs mit Logcat ansehen und schreiben.

Logging-Systemübersicht

Das Android-Logging-System besteht aus einer Reihe strukturierter zirkulärer Zwischenspeicher, die vom Systemprozess logd verwaltet werden. Die Gruppe der verfügbaren Puffer wird vom System festgelegt und festgelegt. Die wichtigsten Puffer sind:

  • main: Speichert die meisten Anwendungslogs.
  • system: Speichert Nachrichten, die aus dem Android-Betriebssystem stammen.
  • crash: Speichert Absturzprotokolle. Jeder Logeintrag hat eine Priorität, ein Tag, das den Ursprung des Logs identifiziert, und die eigentliche Lognachricht.

Die primäre C/C++-Schnittstelle zum Logging-System ist die gemeinsam genutzte Bibliothek liblog und ihr Header <android/log.h>. Alle sprachspezifischen Logging-Funktionen (einschließlich android.util.Log) rufen schließlich die Funktion __android_log_write auf. Standardmäßig wird die Funktion __android_log_logd_logger aufgerufen, die den Logeintrag mit einem Socket an logd sendet. Ab API-Level 30 kann die Logging-Funktion durch Aufrufen von __android_set_log_writer geändert werden. Weitere Informationen finden Sie in der NDK-Dokumentation.

Von adb logcat angezeigte Logs werden vier Stufen der Filterung durchlaufen:

Filterung nach Kompilierungszeit
Abhängig von den Kompilierungseinstellungen werden einige Logs möglicherweise vollständig aus der Binärdatei entfernt. ProGuard kann beispielsweise so konfiguriert werden, dass Aufrufe von Log.d aus Java-Code entfernt werden.
Nach Systemeigenschaften filtern
liblog fragt eine Reihe von Systemattributen ab, um den minimalen Schweregrad zu bestimmen, der an logd gesendet werden soll. Wenn Ihre Logs das Tag MyApp enthalten, werden die folgenden Attribute geprüft und müssen den ersten Buchstaben des Mindestschweregrads enthalten (V, D, I, W, E oder S, um alle Logs zu deaktivieren):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
Anwendungsfilter
Wenn keines der Attribute festgelegt ist, verwendet liblog die von __android_log_set_minimum_priority festgelegte minimale Priorität. Die Standardeinstellung ist INFO.
Displayfilterung
adb logcat unterstützt zusätzliche Filter, mit denen die Anzahl der von logd angezeigten Logs reduziert werden kann. Weitere Informationen finden Sie im Abschnitt zum Filtern der Logausgabe.

Befehlszeilensyntax

Die allgemeine Verwendung zum Ausführen von logcat über die adb-Shell lautet: 

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

Es gibt auch eine Kurzschreibweise von adb logcat, die aber zu adb shell logcat erweitert wird.

Optionen

logcat hat viele Optionen. Welche Optionen verfügbar sind, hängt von der Betriebssystemversion des verwendeten Geräts ab. Führen Sie folgenden Befehl aus, um die Hilfe zu logcat für das verwendete Gerät aufzurufen: 

    adb logcat --help

Da logcat ein Tool für Betriebssystem- und App-Entwickler ist (wobei App-Entwickler voraussichtlich stattdessen Android Studio verwenden), können viele der Optionen nur als root verwendet werden.

Logausgabe filtern

Das Tag einer Lognachricht ist ein kurzer String, der die Systemkomponente angibt, von der die Nachricht stammt. Beispiel: „View“ für das Ansichtssystem.

Die Priorität ist einer der folgenden Zeichenwerte, sortiert von der niedrigsten zur höchsten Priorität:

    • V: Ausführlich (niedrigste Priorität)
    • D: Fehlerbehebung
    • I: Informationen
    • W: Warnung
    • E: Fehler
    • F: Schwerwiegend
    • S: Lautlos (höchste Priorität, bei der nie gedruckt wird)

    • Um eine Liste der im System verwendeten Tags mit Prioritäten zu erhalten, führen Sie logcat aus und beobachten die ersten beiden Spalten jeder Nachricht, die als <priority>/<tag> angegeben werden.

    Das folgende Beispiel zeigt eine kurze logcat-Ausgabe, die mit dem Befehl logcat -v brief output abgerufen wird. Die Ausgabe zeigt, dass sich die Nachricht auf die Prioritätsstufe "I" und das Tag "ActivityManager" bezieht: 

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

    Um die Logausgabe auf ein überschaubares Maß zu reduzieren, beschränken Sie die Logausgabe mithilfe von Filterausdrücken. Mit Filterausdrücken können Sie dem System die gewünschten Kombinationen der Tag-Prioritäten angeben. Das System unterdrückt andere Meldungen für die angegebenen Tags.

    Ein Filterausdruck folgt dem Format tag:priority ..., wobei tag das relevante Tag und priority die minimale Prioritätsstufe angibt, die für dieses Tag gemeldet werden soll. Nachrichten für dieses Tag mit der angegebenen Priorität oder höher werden in das Log geschrieben. Geben Sie eine beliebige Anzahl von tag:priority-Spezifikationen in einem einzelnen Filterausdruck an. Die Reihe der Spezifikationen ist durch Leerzeichen getrennt.

    Im Folgenden finden Sie ein Beispiel für einen Filterausdruck, mit dem alle Logmeldungen mit Ausnahme der Logmeldungen mit dem Tag "ActivityManager" mit der Priorität "Info" oder höher und der mit dem Tag "MyApp" mit der Priorität "Debug" oder höher unterdrückt werden:

    adb logcat ActivityManager:I MyApp:D *:S

    Mit dem letzten Element im vorherigen Ausdruck, *:S, wird die Prioritätsstufe für alle Tags auf „Lautlos“ festgelegt. Dadurch wird sichergestellt, dass nur Logeinträge mit „ActivityManager“ und „MyApp“ angezeigt werden. Mit *:S wird sichergestellt, dass die Logausgabe auf die von Ihnen explizit angegebenen Filter beschränkt ist. Mit *:S können Ihre Filter als Zulassungsliste für die Logausgabe dienen.

    Hinweis:In einigen Shells ist das Zeichen „*“ für die Shell reserviert. Wenn Sie eine solche Shell verwenden, setzen Sie den Filterausdruck in Anführungszeichen: adb logcat "ActivityManager:I MyApp:D *:S"

    Mit dem folgenden Filterausdruck werden alle Logmeldungen mit der Prioritätsstufe „Warnung“ und höher für alle Tags angezeigt:

    adb logcat *:W

    Wenn Sie logcat auf Ihrem Entwicklungscomputer statt in einer Remote-adb-Shell ausführen, können Sie auch einen Standardfilterausdruck festlegen, indem Sie einen Wert für die Umgebungsvariablen ANDROID_LOG_TAGS exportieren:

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

    Der Filter ANDROID_LOG_TAGS wird nicht in den Emulator bzw. die Geräteinstanz exportiert, wenn Sie logcat über eine Remote-Shell ausführen oder adb shell logcat verwenden.

    Ausgabeformat des Steuerprotokolls

    Neben dem Tag und der Priorität enthalten Lognachrichten eine Reihe von Metadatenfeldern. Sie können das Ausgabeformat für Nachrichten so ändern, dass sie ein bestimmtes Metadatenfeld anzeigen. Verwenden Sie dazu die Option -v und geben Sie eines der folgenden unterstützten Ausgabeformate an:

    • brief: Zeigt die Priorität, das Tag und die PID des Prozesses an, von dem die Nachricht stammt.
    • long: Zeigt alle Metadatenfelder und separate Nachrichten mit Leerzeilen an.
    • process: Zeigt nur die PID an.
    • raw: Zeigt die unformatierte Protokollnachricht ohne weitere Metadatenfelder an.
    • tag: Hier werden nur die Priorität und das Tag angezeigt.
    • thread:: Ein Legacy-Format, das Priorität, PID und TID des Threads anzeigt, der die Nachricht ausstellt.
    • threadtime (Standard): Zeigt das Datum, die Aufrufzeit, die Priorität, das Tag, die PID und die TID des Threads an, der die Nachricht ausstellt.
    • time: Zeigt das Datum, die Aufrufzeit, die Priorität, das Tag und die PID des Prozesses an, der die Nachricht ausgibt.

    Geben Sie beim Starten von logcat mit der Option -v das gewünschte Ausgabeformat an:

    [adb] logcat [-v <format>]

    Das folgende Beispiel zeigt, wie Nachrichten im thread-Ausgabeformat generiert werden:

    adb logcat -v thread

    Mit der Option -v können Sie nur ein Ausgabeformat angeben. Sie können jedoch beliebig viele Modifikatoren angeben, sofern sie sinnvoll sind. logcat ignoriert Modifikatoren, die keinen Sinn ergeben.

    Formatmodifikatoren

    Formatmodifikatoren ändern die logcat-Ausgabe. Verwenden Sie die Option -v so, um einen Formatmodifikator anzugeben: 

    adb logcat -b all -v color -d

    Jeder Android-Lognachricht ist ein Tag und eine Priorität zugeordnet. Sie können einen Formatmodifikator mit einer der folgenden Formatoptionen kombinieren:

    • brief
    • long
    • process
    • raw
    • tag
    • thread
    • threadtime
    • time

    Geben Sie in die Befehlszeile logcat -v --help ein, um die folgenden Modifikatordetails zu formatieren:

    • color: Jede Prioritätsstufe wird in einer anderen Farbe angezeigt.
    • descriptive: Zeigt Beschreibungen von Protokollzwischenspeicherereignissen an. Dieser Modifikator wirkt sich nur auf Zwischenspeichernachrichten für Ereignisprotokolle aus und hat keine Auswirkungen auf die anderen nicht binären Puffer. Die Ereignisbeschreibungen stammen aus der Ereignislog-Tag-Datenbank.
    • epoch: Die Zeit wird in Sekunden ab dem 1. Januar 1970 angezeigt.
    • monotonic: Zeigt die Zeit in CPU-Sekunden ab dem letzten Start an.
    • printable: stellt sicher, dass Inhalte im binären Logging mit Escapezeichen versehen werden.
    • uid: Zeigt die UID oder Android-ID des protokollierten Prozesses an, sofern dies für die Zugriffssteuerungen zulässig ist.
    • usec: Zeigt die Zeit in Mikrosekunden an.
    • UTC: Die Zeit wird als UTC angezeigt.
    • year: Damit wird das Jahr zur angezeigten Zeit hinzugefügt.
    • zone: Fügt die lokale Zeitzone zur angezeigten Zeit hinzu.

    Alternative Protokollzwischenspeicher ansehen

    Das Logging-System von Android behält mehrere temporäre Zwischenspeicher für Log-Nachrichten vor und nicht alle Log-Nachrichten werden an den standardmäßigen zirkulären Zwischenspeicher gesendet. Zum Anzeigen zusätzlicher Logeinträge führen Sie den Befehl logcat mit der Option -b aus, um die Anzeige eines alternativen zirkulären Zwischenspeichers anzufordern. Sie können einen beliebigen dieser alternativen Puffer anzeigen:

    • radio: ruft den Zwischenspeicher auf, der Radio-/Telefonienachrichten enthält.
    • events: zeigt die interpretierten binären Systemereignis-Zwischenspeichermeldungen an.
    • main: Ruft den Log-Hauptzwischenspeicher auf (Standardeinstellung), der keine System- und Absturz-Log-Nachrichten enthält.
    • system: Ruft den Systemprotokollzwischenspeicher auf (Standardeinstellung).
    • crash: Ruft den Absturzprotokollzwischenspeicher auf (Standardeinstellung).
    • all: Aufrufe aller Zwischenspeicher.
    • default: Puffer für Berichte main, system und crash ein.

    Die Option -b wird folgendermaßen verwendet:

    [adb] logcat [-b <buffer>]

    Hier ist ein Beispiel, wie Sie einen Protokollpuffer mit Funk- und Telefonienachrichten aufrufen können: 

    adb logcat -b radio

    Geben Sie Folgendes ein, um mehrere -b-Flags für alle Zwischenspeicher anzugeben, die Sie ausgeben möchten: 

    logcat -b main -b radio -b events

    Geben Sie ein einzelnes -b-Flag mit einer durch Kommas getrennten Liste von Puffern an. Beispiel: 

    logcat -b main,radio,events

    Aus Code protokollieren

    Mit der Klasse Log können Sie Logeinträge im Code erstellen, die im logcat-Tool angezeigt werden. Zu den gängigen Protokollierungsmethoden gehören:

    Verwenden Sie beispielsweise den folgenden Aufruf:

    Kotlin

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

    Java

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

    Die Ausgabe von logcat sieht in etwa so aus:

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