Strumento a riga di comando Logcat

Logcat è uno strumento a riga di comando che scarica un log dei messaggi di sistema, inclusi quelli scritti dalla tua app con la classe Log.

Questa pagina riguarda lo strumento logcat a riga di comando, ma puoi visualizzare i messaggi di log anche dalla finestra Logcat in Android Studio. Per informazioni su come visualizzare e filtrare i log da Android Studio, consulta Visualizzare e scrivere i log con Logcat.

Panoramica del sistema di logging

Il sistema di logging di Android è un insieme di buffer circolari strutturati gestiti dal processo di sistema logd. Il set di buffer disponibili è fisso e definito dal sistema. I buffer più rilevanti sono:

  • main: archivia la maggior parte dei log delle applicazioni.
  • system: archivia i messaggi provenienti dal sistema operativo Android.
  • crash: archivia i log degli arresti anomali. Ogni voce di log ha una priorità, un tag che identifica l'origine del log e il messaggio di log effettivo.

L'interfaccia C/C++ principale per il sistema di logging è la libreria condivisa liblog e la relativa intestazione <android/log.h>. Tutte le strutture di logging specifiche per la lingua (tra cui android.util.Log) chiamano infine la funzione __android_log_write. Per impostazione predefinita, chiama la funzione __android_log_logd_logger, che invia la voce di log a logd utilizzando un socket. A partire dal livello API 30, la funzione di logging può essere modificata chiamando __android_set_log_writer. Ulteriori informazioni sono disponibili nella documentazione di NDK.

I log visualizzati da adb logcat vengono sottoposti a quattro livelli di filtraggio:

Filtro tempo di compilazione
A seconda delle impostazioni di compilazione, alcuni log potrebbero essere stati completamente rimossi dal programma binario. Ad esempio, ProGuard può essere configurato per rimuovere le chiamate a Log.d dal codice Java.
Filtro delle proprietà di sistema
liblog esegue query su un insieme di proprietà di sistema per determinare il livello di gravità minimo da inviare a logd. Se i log presentano il tag MyApp, vengono controllate le seguenti proprietà e dovrebbero contenere la prima lettera del livello minimo di gravità (V, D, I, W, E o S per disattivare tutti i log):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
Filtro delle applicazioni
Se nessuna delle proprietà è impostata, liblog utilizza la priorità minima impostata da __android_log_set_minimum_priority. L'impostazione predefinita è INFO.
Filtro display
adb logcat supporta filtri aggiuntivi che possono ridurre la quantità di log visualizzati a partire dal giorno logd. Per ulteriori dettagli, consulta la sezione relativa al filtro dell'output dei log.

Sintassi della riga di comando

Per eseguire logcat tramite la shell adb, l'utilizzo generale è:

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

C'è anche un'abbreviazione di adb logcat, che però si espande solo in adb shell logcat.

Opzioni

logcat ha molte opzioni. Le opzioni disponibili dipendono dalla versione del sistema operativo del dispositivo in uso. Per visualizzare la guida per logcat specifica per il dispositivo che stai utilizzando, esegui:

    adb logcat --help
    

Tieni presente che, poiché logcat è uno strumento per sviluppatori di sistemi operativi e di app (gli sviluppatori di app dovrebbero invece utilizzare Android Studio), molte opzioni sono utilizzabili solo come root.

Filtra output di log

Il tag di un messaggio di log è una breve stringa che indica il componente di sistema da cui ha origine il messaggio. Ad esempio, "Visualizza" per il sistema di visualizzazione.

La priorità è uno dei seguenti valori di carattere, in ordine di priorità (dal più basso al più alto):

    • V: dettagliato (priorità più bassa)
    • D: debug
    • I: informazioni
    • W: avviso
    • E: errore
    • F: irreversibile
    • S: silenzioso (con priorità massima, dove non viene mai stampato nulla)
  • Per ottenere un elenco dei tag utilizzati nel sistema con priorità, esegui logcat e osserva le prime due colonne di ogni messaggio, indicate come <priority>/<tag>.

    Di seguito è riportato un esempio di breve output logcat ottenuto con il comando logcat -v brief output. L'output mostra che il messaggio riguarda il livello di priorità "I" e il tag "ActivityManager":

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

    Per ridurre l'output dei log a un livello gestibile, limita l'output dei log utilizzando espressioni di filtro. Le espressioni di filtro consentono di indicare al sistema le combinazioni con priorità ai tag che ti interessano. Il sistema elimina gli altri messaggi per i tag specificati.

    Un'espressione di filtro segue questo formato tag:priority ..., dove tag indica il tag che ti interessa e priority indica il livello di priorità minimo per il report di quel tag. I messaggi per quel tag con priorità pari o superiore a quella specificata vengono scritti nel log. Fornisci un numero qualsiasi di specifiche tag:priority in una singola espressione di filtro. La serie delle specifiche è delimitata da spazi vuoti.

    Di seguito è riportato un esempio di espressione di filtro che elimina tutti i messaggi di log tranne quelli con il tag "ActivityManager" con priorità "Info" o superiore e quelli con il tag "Miaapp" con priorità "Debug" o superiore:

    adb logcat ActivityManager:I MyApp:D *:S
    

    L'elemento finale nell'espressione precedente, *:S, imposta il livello di priorità di tutti i tag su "silenzioso", in modo che vengano visualizzati solo i messaggi di log con "ActivityManager" e "Miaapp". L'utilizzo di *:S assicura che l'output del log sia limitato ai filtri che hai specificato esplicitamente. *:S consente ai filtri di fungere da lista consentita per l'output di log.

    Nota:in alcune shell, il carattere "*" è riservato dalla shell. Se utilizzi una shell di questo tipo, racchiudi l'espressione di filtro tra virgolette: adb logcat "ActivityManager:I MyApp:D *:S"

    La seguente espressione di filtro mostra tutti i messaggi di log con livello di priorità "avviso" e superiore per tutti i tag:

    adb logcat *:W
    

    Se esegui logcat dal tuo computer di sviluppo invece di eseguirlo su una shell adb remota, puoi anche impostare un'espressione di filtro predefinita esportando un valore per la variabile di ambiente ANDROID_LOG_TAGS:

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

    Il filtro ANDROID_LOG_TAGS non viene esportato nell'emulatore/nell'istanza del dispositivo se esegui logcat da una shell remota o utilizzando adb shell logcat.

    Formato di output del log di controllo

    I messaggi di log contengono una serie di campi di metadati, oltre al tag e alla priorità. Puoi modificare il formato di output dei messaggi in modo che mostrino un campo di metadati specifico. Per farlo, utilizza l'opzione -v e specifica uno dei seguenti formati di output supportati:

    • brief: mostra priorità, tag e PID del processo che ha emesso il messaggio.
    • long: mostra tutti i campi di metadati e i messaggi separati con righe vuote.
    • process: mostra solo il PID.
    • raw: visualizza il messaggio di log non elaborato senza altri campi di metadati.
    • tag: mostra solo la priorità e il tag.
    • thread: Un formato precedente che mostra priorità, PID e TID del thread che ha inviato il messaggio.
    • threadtime (impostazione predefinita): mostra la data, l'ora della chiamata, la priorità, il tag, il PID e il TID del thread che emette il messaggio.
    • time: mostra la data, l'ora della chiamata, la priorità, il tag e il PID del processo che ha emesso il messaggio.

    Quando avvii logcat, specifica il formato di output desiderato utilizzando l'opzione -v:

    [adb] logcat [-v <format>]
    

    Ecco un esempio che mostra come generare messaggi nel formato di output thread:

    adb logcat -v thread
    

    Puoi specificare un solo formato di output con l'opzione -v. Tuttavia, puoi specificare tutti i modificatori necessari, a condizione che abbiano senso. logcat ignora i modificatori non significativi.

    Modificatori di formato

    I modificatori di formato modificano l'output di logcat. Per specificare un modificatore di formato, utilizza l'opzione -v, come segue:

    adb logcat -b all -v color -d
    

    A ogni messaggio di log di Android è associato un tag e una priorità. Puoi combinare qualsiasi modificatore di formato con una delle seguenti opzioni di formato:

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

    Per formattare i seguenti dettagli del modificatore, inserisci logcat -v --help nella riga di comando:

    • color: mostra ogni livello di priorità con un colore diverso.
    • descriptive: mostra le descrizioni degli eventi del buffer log. Questo modificatore interessa solo i messaggi del buffer dei log eventi e non ha alcun effetto sugli altri buffer non binari. Le descrizioni degli eventi provengono dal database event-log-tags.
    • epoch: mostra il tempo in secondi a partire dal 1° gennaio 1970.
    • monotonic: mostra il tempo in secondi CPU a partire dall'ultimo avvio.
    • printable: assicura che tutti i contenuti dei log binari siano preceduti da caratteri di escape.
    • uid: se consentito dai controlli di accesso, mostra l'UID o l'ID Android del processo registrato.
    • usec: visualizza l'ora con precisione in microsecondi.
    • UTC: mostra l'ora nel formato UTC.
    • year: aggiunge l'anno all'ora visualizzata.
    • zone: aggiunge il fuso orario locale all'ora visualizzata.

    Visualizza buffer log alternativi

    Il sistema di logging di Android conserva più buffer circolari per i messaggi di log e non tutti i messaggi di log vengono inviati al buffer circolare predefinito. Per visualizzare messaggi di log aggiuntivi, esegui il comando logcat con l'opzione -b per richiedere la visualizzazione di un buffer circolare alternativo. Puoi visualizzare i seguenti buffer alternativi:

    • radio: visualizza il buffer che contiene i messaggi relativi a radio/telefonia.
    • events: visualizza i messaggi del buffer degli eventi del sistema binario interpretati.
    • main: visualizza il buffer del log principale (predefinito), che non contiene i messaggi di log del sistema e degli arresti anomali.
    • system: visualizza il buffer del log di sistema (impostazione predefinita).
    • crash: visualizza il buffer del log degli arresti anomali (impostazione predefinita).
    • all: visualizza tutti i buffer.
    • default: segnala buffer main, system e crash.

    L'opzione -b viene utilizzata nei seguenti casi:

    [adb] logcat [-b <buffer>]
    

    Ecco un esempio di come visualizzare un buffer log contenente messaggi radio e di telefonia:

    adb logcat -b radio
    

    Per specificare più flag -b per tutti i buffer che vuoi stampare, inserisci quanto segue:

    logcat -b main -b radio -b events
    

    Specifica un singolo flag -b con un elenco di buffer separati da virgole, ad esempio:

    logcat -b main,radio,events
    

    Registra da codice

    La classe Log consente di creare voci di log nel codice che vengono visualizzate nello strumento logcat. I metodi più comuni di logging includono:

    Ad esempio, utilizzando la seguente chiamata:

    Kotlin

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

    Java

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

    logcat restituisce un risultato simile al seguente:

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