Logcat — cos'è, livelli di logging e lavoro con i log

Cos'è Logcat in Android

Logcat è un buffer di sistema Android in cui tutti i processi (inclusi kernel Linux, system_server e applicazioni) scrivono messaggi in un formato specifico. Lo strumento logcat, incluso nell'Android SDK, legge questo buffer e visualizza i messaggi in tempo reale. A partire da Android 4.1 (API 16), l'accesso a Logcat è limitato: le applicazioni possono leggere solo i propri log e i log di sistema sono accessibili tramite ADB con accesso di debug.

Ogni messaggio Logcat contiene cinque campi: data e ora, PID (identificatore di processo), TID (identificatore di thread), livello di log e tag. Il formato è fisso e identico in tutte le versioni di Android. Ciò consente di utilizzare le utilità grep, awk e sed per filtrare i log nelle pipeline CI/CD senza dipendenza dall'IDE.

I log sono memorizzati in un buffer circolare di dimensione fissa: 256 KB per main, 256 KB per system e 256 KB per events (Android 5+). Quando il buffer si riempie, i messaggi vecchi vengono eliminati. Lo sviluppatore può modificare la dimensione del buffer tramite la proprietà PROP logcat.size o nelle opzioni sviluppatore del dispositivo.

Livelli di log e tag: struttura del messaggio Logcat

Sei livelli di logging determinano l'importanza del messaggio. Android utilizza livelli standard simili ad altre piattaforme ma con i propri nomi di costanti nella classe Log. Scegliere il livello giusto aiuta a filtrare i log in modo efficiente ed evitare che i messaggi critici vengano sommersi da quelli secondari.

Tag: organizzazione dei messaggi per moduli

Il tag è una stringa di massimo 23 caratteri che identifica la sorgente del messaggio. Si consiglia di utilizzare il nome della classe o del modulo come tag: MainActivity, AuthManager, NetworkModule. Ciò consente di filtrare i log per un componente specifico dell'applicazione. Per uniformità nel team, è possibile creare costanti di tag in un file separato o utilizzare la libreria Timber, che inserisce automaticamente il tag in base al nome della classe.

Log di crash e stack trace di eccezioni

Quando si verifica un'eccezione non gestita, Android scrive automaticamente lo stack trace completo in Logcat, indicando la classe, il metodo, la riga di codice e la catena di chiamate. Il log di crash contiene il tipo di eccezione (NullPointerException, RuntimeException), il messaggio e la sequenza di chiamate dal punto di crash al punto di ingresso dell'applicazione. Per analizzare i log di crash dai dispositivi degli utenti, viene utilizzato Firebase Crashlytics, che sincronizza lo stack trace con la mappa di offuscamento (mapping.txt per Android).

Logcat in Android Studio: interfaccia, filtri e ricerca

Android Studio fornisce un'interfaccia grafica Logcat accessibile tramite View → Tool Windows → Logcat (Alt + 6). La finestra Logcat si aggiorna in tempo reale, mostra tutti i messaggi del dispositivo connesso e consente di configurare filtri flessibili per isolare le informazioni desiderate dal flusso generale.

Filtraggio per livello e tag

L'elenco a discesa Log Level filtra i messaggi per livello minimo: seleziona WARN per vedere solo avvisi ed errori, nascondendo VERBOSE, DEBUG e INFO. Il campo Cerca consente di cercare per testo del messaggio o tag — le regex sono supportate, comodo per trovare messaggi per pattern.

Filtri salvati

I Saved Filters sono una potente funzionalità di Logcat in Android Studio. Puoi creare un filtro che mostra solo i messaggi con il tag della tua applicazione (tag:MyApp) e livello WARN+. I filtri vengono conservati tra le sessioni e sono disponibili dall'elenco a discesa. Per progetti con più moduli, crea un filtro separato per ogni modulo.

# Espressione di esempio per filtrare i log dell'applicazione
tag:"MyApp" level:WARN # Solo WARN+ per MyApp
package:"com.mycompany" # Tutti i log del pacchetto
-tag:"okhttp" # Escludere i log di OkHttp

Esportazione e analisi

I log di Logcat possono essere esportati in un file di testo tramite l'icona Save to File. Ciò è utile per allegarli a ticket Jira o analizzare sessioni lunghe. Il log esportato può essere aperto in qualsiasi editor di testo e si può applicare grep per cercare pattern. Per una visualizzazione formattata, utilizza l'utilità logcat-color.

ADB logcat: comandi terminale per lavoro avanzato

ADB logcat è la versione console di Logcat, accessibile tramite Android Debug Bridge. Il suo principale vantaggio è la possibilità di eseguirlo su server CI, in script di automazione e su dispositivi senza Android Studio. ADB logcat supporta tutti gli stessi filtri della GUI, ma con la flessibilità della riga di comando.

Comandi di base

Il comando adb logcat senza argomenti restituisce l'intero buffer in tempo reale. Usa Ctrl+C per fermarlo. Il flag -c pulisce il buffer prima di iniziare la registrazione — utile quando è necessario isolare i log del test corrente dai messaggi precedenti. Il flag -b seleziona il tipo di buffer: main, system, events, crash (Android 12+).

# Pulire il buffer e avviare la registrazione dei log con il tag MyApp
adb logcat -c
adb logcat MyApp:D *:S

# Salvare i log in un file
adb logcat -d > logcat_dump.txt

# Filtraggio per PID del processo
adb logcat --pid=12345

Filtraggio con grep e awk

Combinare ADB con utilità Unix offre la massima flessibilità. Ad esempio, il filtro "*:S TAG:D" mostra solo i messaggi con il tag TAG di livello DEBUG e superiore, nascondendo tutti gli altri. Per vedere solo le eccezioni, usa grep -i exception. Per analizzare la frequenza degli errori, applica sort | uniq -c sulla colonna del tag.

Logcat in CI/CD

Sui server CI, Logcat viene utilizzato per raccogliere diagnostica durante l'esecuzione dei test UI. Una pipeline tipica: pulire il buffer prima di eseguire i test, salvare il dump dei log come artefatto di build dopo l'esecuzione dei test. Se un test fallisce, i log possono determinare se il fallimento è stato causato da ANR, eccezione non gestita o timeout di rete.

Logging nel codice: Log.d, Log.e e Timber

La classe android.util.Log è l'API integrata per scrivere messaggi in Logcat. Log.v, Log.d, Log.i, Log.w, Log.e e Log.wtf accettano un tag (stringa) e un messaggio (stringa) o un messaggio + Throwable. Per formattare i messaggi, usa String.format o i template stringa di Kotlin — evita la concatenazione di stringhe, che crea oggetti inutili nell'heap.

La libreria Timber

Timber è una libreria popolare di Jake Wharton che supera le carenze dell'API Log integrata. Timber inserisce automaticamente il tag in base al nome della classe che ha chiamato il logging e non richiede il passaggio di un tag in ogni chiamata. Timber supporta anche il logging condizionale: nelle build Release, le chiamate Timber.v e Timber.d possono essere disattivate con una singola riga in Application.onCreate.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // API Log integrata
        Log.d("MainActivity", "onCreate called")

        // Timber — tag automatico per nome classe
        Timber.d("onCreate called")
    }

    private fun loadData() {
        try {
            val result = fetchFromNetwork()
            Timber.i("Data loaded: $result")
        } catch (e: IOException) {
            Timber.e(e, "Failed to load data")
        }
    }
}

Logging condizionale per Release

Nelle build Release si consiglia di disattivare i log VERBOSE e DEBUG per ridurre il carico sul buffer Logcat ed evitare la fuga di informazioni sensibili. Timber risolve questo problema con PlantingTree: nella variante Debug viene piantato DebugTree (registra tutto), in Release — CrashReportingTree (registra solo ERROR tramite Crashlytics). L'API Log integrata non supporta il logging condizionale — lo sviluppatore deve avvolgere ogni chiamata con if (BuildConfig.DEBUG).