Console.app: cos'è, funzionalità e come leggere i log in macOS

Cos'è Console.app

Console.app è un'interfaccia grafica per il sistema di logging unificato di Apple. Ha sostituito la vecchia applicazione Console (come parte di macOS) e fornisce accesso a tutti i log di sistema e delle applicazioni scritti tramite le API os_log, os_trace e syslog. Console.app si trova in /Applications/Utilities/ su qualsiasi Mac.

A differenza di Xcode, che mostra solo i log dell'applicazione avviata dall'IDE, Console.app mostra contemporaneamente i log di tutti i processi sul sistema. Ciò consente di diagnosticare problemi che si verificano solo quando l'applicazione viene avviata al di fuori di Xcode o in background. Console.app mostra anche i log di sistema — kernel, launchd, WindowServer — utili per il debug di problemi di basso livello.

Console.app non richiede installazione di strumenti aggiuntivi o connessione Internet. Tutti i dati vengono memorizzati localmente in un database .tracev3 e l'applicazione funziona completamente offline. Per visualizzare i log da un altro Mac o dispositivo iOS, utilizzare il comando log collect e quindi aprire il .logarchive in Console.app.

Interfaccia di Console.app

L'interfaccia di Console.app è composta da tre aree principali: la barra laterale con i filtri, la tabella dei messaggi e il pannello dei dettagli del messaggio selezionato. La barra laterale contiene le sezioni Devices (sorgenti di log disponibili), Reports (report di crash di sistema) e Saved Searches (query di ricerca salvate).

La tabella dei messaggi mostra un elenco di log con colonne: Time (timestamp), Category (categoria), Level (livello di criticità — codificato a colori), Process (nome del processo), Message (testo del messaggio). Cliccando su un messaggio si apre il pannello dei dettagli che mostra il sottosistema, l'identificatore di attività, l'ID del thread e il testo completo formattato.

Console.app evidenzia i messaggi a colori: rosso per Fault, giallo per Error, blu per Debug, grigio per Info. I messaggi predefiniti non vengono evidenziati. Ciò consente di scansionare visivamente il flusso di log e notare immediatamente gli eventi critici.

// Log che appariranno in Console.app
import OSLog

let logger = Logger(
    subsystem: "com.example.myapp",
    category: "network"
)

logger.error("Connection failed: timeout")
logger.debug("Retry attempt 3 of 5")

// Questi messaggi sono visibili in Console.app con il filtro "myapp"

Filtri e ricerca in Console.app

Il filtraggio è la funzione principale di Console.app, che trasforma un flusso di migliaia di messaggi al secondo in un elenco leggibile. Il campo di ricerca nella parte superiore supporta condizioni AND: più parole separate da uno spazio mostrano solo i messaggi contenenti tutte le parole. Ad esempio, myapp error mostra tutti i log dell'applicazione myapp con livello Error.

Filtro per sottosistema nella barra laterale consente di selezionare uno o più sottosistemi. Questo è il modo più rapido per isolare i log di un'applicazione specifica dai messaggi di sistema. Filtro per categoria è disponibile dopo aver selezionato un sottosistema — mostra tutte le categorie utilizzate dall'applicazione selezionata. Filtro per livello limita i messaggi per livello di criticità: è possibile mostrare solo errori o solo messaggi di debug.

Espressioni regolari nella ricerca

Il campo di ricerca di Console.app supporta le regex tramite la costruzione REGEX:pattern. Esempio: REGEX:error.*tim(e|out) trova tutti i messaggi contenenti “error” e una parola che inizia con “tim” e termina con “e” o “out”. Le regex funzionano solo nel campo di ricerca, non nei filtri per sottosistema o categoria.

Modalità Live e Historical

Live è la modalità in tempo reale in cui Console.app mostra nuovi messaggi non appena compaiono nel buffer circolare del kernel. Questa modalità è attiva per impostazione predefinita ed è adatta per il debug di un'applicazione in esecuzione: si avvia l'applicazione e se ne vedono i log con un ritardo di 1–5 secondi. Il pulsante Live (o ⌘L) attiva e disattiva il flusso.

Historical è la modalità di visualizzazione dell'archivio. Console.app memorizza tutti i messaggi degli ultimi 7–14 giorni (configurabile nel sistema) in un database .tracev3. La modalità Historical apre questo archivio e consente di cercare al suo interno utilizzando qualsiasi filtro, non solo il flusso corrente. Ciò è indispensabile per analizzare problemi verificatisi durante la notte o quando l'applicazione era in esecuzione senza essere collegata a un Mac.

Il passaggio tra le modalità avviene tramite il pulsante Live nella barra degli strumenti. Quando Live è disattivato, Console.app mostra i dati storici. In questa modalità è possibile navigare nella sequenza temporale utilizzando il calendario o i pulsanti ← →. I dati storici sono disponibili solo per i log salvati su disco — i messaggi sovrascritti nel buffer circolare non compaiono nell'archivio.

Esportazione e condivisione dei log

Console.app supporta l'esportazione dei log filtrati in diversi formati. File → Export → Save consente di scegliere il formato: .logarchive (formato nativo di Apple, include tutti i metadati), .txt (testo semplice con colonne) e .json (dati strutturati con campi). Per allegare a una segnalazione di bug, utilizzare .logarchive — può essere aperto su qualsiasi Mac in Console.app.

Esportazione da un dispositivo iOS: tramite Xcode (Devices → Open Console) o tramite il comando log collect --device --output ./archive.logarchive nel terminale. Aprire il .logarchive risultante in Console.app su un Mac — i log provengono dal dispositivo remoto, ma i filtri e la ricerca funzionano come con i log locali.

// Esportazione dei log di dispositivi iOS tramite terminale
// log collect --device --output ./ios_crash.logarchive
// log show --subsystem com.example.app --last 1h --output json

// Esempio: esportare i log dell'ultima ora
// log show --predicate 'subsystem == "com.example.myapp"' \
//   --info --debug --last 1h --output json > logs.json

// Analisi dei log esportati in Swift
let jsonData = try Data(contentsOf: URL(fileURLWithPath: "logs.json"))
let decoded = try JSONDecoder()
    .decode([LogEntry].self, from: jsonData)

Condivisione dei log

.logarchive è il formato ottimale per inviare a un collega o allegare a un ticket JIRA. Il file contiene non solo messaggi ma anche sottosistema, categoria, timestamp, ID thread e tutti i metadati. Le dimensioni dell'archivio sono significativamente inferiori rispetto ai log grezzi grazie alla compressione .tracev3. Prima dell'invio, assicurarsi che i log non contengano dati privati: utilizzare un filtro per sottosistema dell'applicazione per escludere i log di sistema che potrebbero contenere informazioni riservate di altri processi.

Esempi pratici di debug con Console.app

Diagnostica dei crash senza Xcode: se un'applicazione si blocca all'avvio al di fuori di Xcode, Console.app mostrerà un messaggio Fault dal processo. Cercare Reports → Crash Reports nella barra laterale — vengono visualizzati report di crash completi con firma e stack. Utilizzare il filtro per sottosistema dell'applicazione e impostare il livello Error+Fault per vedere tutti gli eventi critici prima del crash.

Analisi delle prestazioni tramite Console.app

Console.app consente di tracciare i ritardi nell'applicazione utilizzando i timestamp. Se tra due messaggi correlati (ad esempio, “richiesta inviata” e “risposta ricevuta”) è trascorso più tempo del previsto, questo è un segnale di problema di prestazioni. Un filtro sul sottosistema dell'applicazione con livello Default mostrerà tutti gli eventi chiave con precisione al millisecondo.

Ricerca di perdite di memoria: quando si verifica una perdita di memoria, il sistema invia un avviso di memoria tramite os_log con categoria memory e livello Error. In Console.app, filtrare per la parola memory e selezionare il proprio sottosistema. Se l'avviso si ripete ogni 5–10 secondi, l'applicazione sta consumando attivamente memoria. È anche possibile attivare i log Debug per tracciare le allocazioni.

Debug delle richieste di rete: se l'applicazione utilizza os_log per eventi di rete, Console.app mostrerà tutte le richieste e risposte con tempistiche. Un filtro category=network riduce il rumore. Se il tempo tra una richiesta e una risposta supera le aspettative, cercare messaggi con level=Error — indicheranno timeout o errori DNS.

// Struttura per l'analisi dei log JSON di Console.app
struct LogEntry: Codable {
    let timestamp: String
    let eventMessage: String
    let subsystem: String
    let category: String
    let messageType: UInt8

    var level: String {
        switch messageType {
        case 1: return "Fault"
        case 16: return "Error"
        case 17: return "Debug"
        default: return "Default"
        }
    }
}