os_log: cos'è, funzionalità e funzionamento del logging unificato in Apple

Cos'è os_log

os_log è un'API di logging unificato presentata da Apple in iOS 10 e macOS Sierra. Ha unificato i meccanismi di logging disparati NSLog, os_trace e syslog in un unico sistema con bufferizzazione a livello di kernel XNU.

A differenza di NSLog, che scrive ogni messaggio in modo sincrono su disco e blocca il thread, os_log utilizza un buffer circolare asincrono in memoria. I messaggi vengono scaricati su disco solo quando l'attività supera una soglia impostata o su comando log collect. Ciò riduce radicalmente l'impatto del logging sulle prestazioni dell'applicazione.

os_log supporta sei livelli di criticità, differenziazione per subsystem e category e un meccanismo di privacy integrato: i dati contrassegnati come private vengono automaticamente mascherati nei log di produzione e sono disponibili solo per lo sviluppatore quando connesso tramite Xcode.

Storia del logging unificato

Prima di iOS 10, gli sviluppatori utilizzavano NSLog per il debug e syslog per i messaggi di sistema. NSLog scriveva su stderr e sulla console, ma era estremamente inefficiente: ogni messaggio veniva scritto in modo sincrono su disco, causando ritardi nell'interfaccia utente con logging frequente. os_log ha risolto questo problema spostando la bufferizzazione nella parte BSD del kernel XNU e rendendo asincrone le scritture su disco.

Dove viene utilizzato os_log

os_log viene utilizzato in tutte le applicazioni Apple ed è raccomandato da Apple come unica API di logging per iOS, macOS, tvOS e watchOS. Il sistema e le applicazioni di terze parti scrivono messaggi attraverso di esso in un database unificato — viene memorizzato in memoria e scaricato periodicamente su disco. Questi log possono essere analizzati tramite Console.app su Mac o tramite il comando log nel terminale.

Come funziona os_log: architettura e bufferizzazione

L'architettura di os_log è composta da tre strati: un'API lato client nello spazio utente (libsystem_trace.dylib), un buffer circolare nel kernel XNU e il demone logd che scarica il buffer in modo asincrono su disco.

Quando un'applicazione chiama os_log, il messaggio viene copiato in un buffer circolare del kernel di diversi megabyte. Il buffer opera sul principio FIFO: se è pieno, i messaggi più vecchi vengono sovrascritti da quelli più nuovi. Il demone logd controlla periodicamente il buffer e salva i messaggi in file .tracev3 in un'area protetta del file system.

Secondo Apple Engineering, il ritardo tipico dalla chiamata di os_log alla comparsa del messaggio in Console.app è di 1–5 secondi su un dispositivo e fino a 60 secondi durante lo scaricamento su disco in modalità batch. Si tratta di un compromesso deliberato: le prestazioni dell'applicazione non vengono influenzate dal logging, ma lo sviluppatore vede i messaggi con un lieve ritardo.

// Dichiarazione di os_log tramite OSLog
import OSLog

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

Buffer circolare e sua configurazione

Il buffer circolare di os_log ha una dimensione fissa e non può essere modificato dallo spazio utente. La dimensione del buffer varia da 256 KB su Apple Watch a 4 MB su Mac. Quando un'applicazione genera più messaggi di quanti il buffer possa contenerne, i messaggi più vecchi vengono persi — questo è un comportamento previsto per il logging ad alto volume.

Per la raccolta a lungo termine di tutti i messaggi, viene utilizzato il comando log collect. Avvia un demone di raccolta sul dispositivo ed esporta un .logarchive sul computer dello sviluppatore. In questa modalità, il buffer non viene sovrascritto — i messaggi vengono scritti direttamente nell'archivio.

Livelli di os_log: Default, Info, Debug, Error, Fault

os_log supporta cinque livelli di criticità, ciascuno responsabile di un diverso tipo di messaggio e elaborato in modo diverso dal sistema. Default è il livello base per i messaggi che entrano sempre nel buffer. Info e Debug sono disabilitati nelle build di produzione senza un profilo di raccolta. Error e Fault sono sempre attivi e contrassegnati con un flag speciale nel database.

Scegliere il corretto livello di criticità è importante per le prestazioni: Info e Debug non vengono scritti su disco in modalità normale, quindi possono essere utilizzati abbondantemente senza il rischio di rallentare l'applicazione. Error e Fault vengono sempre salvati, ma la loro quantità dovrebbe essere minima — ciascuno di questi messaggi aumenta il tempo di scrittura a causa dei metadati aggiuntivi.

Categorie e subsystem in os_log

Subsystem è un identificatore di applicazione o modulo nel formato reverse-DNS (com.example.app). Category è un'etichetta testuale all'interno di un subsystem che raggruppa i log per aree funzionali: network, ui, database, auth. Questa gerarchia consente di filtrare i log senza leggere ogni messaggio e di raccogliere statistiche per ogni modulo separatamente.

Apple raccomanda di definire un OSLog per modulo e di utilizzarlo in tutti i file di quel modulo. Per i diversi strati dell'applicazione — networking, UI, persistenza — è necessario creare categorie separate. Quindi in Console.app puoi abilitare i log solo per network e disabilitarli per gli altri senza ricompilare l'applicazione.

import OSLog

extension Logger {
    static let network = Logger(
        subsystem: "com.example.app",
        category: "network"
    )
    static let ui = Logger(
        subsystem: "com.example.app",
        category: "ui"
    )
}

Privacy dei dati in os_log

os_log fornisce un meccanismo di controllo della privacy integrato: ogni valore in una stringa di formato può essere contrassegnato come public, private o auto (comportamento predefinito). Per impostazione predefinita, os_log considera tutte le stringhe dinamiche e gli oggetti come potenzialmente sensibili e li sostituisce con la maschera <private> nei log di produzione.

Questo è fondamentale per la conformità a GDPR e HIPAA: se un'applicazione registra l'email o il numero di carta di un utente tramite os_log in modalità automatica, i dati reali non raggiungono mai il disco. Lo sviluppatore vede il messaggio completo solo quando è connesso tramite Xcode o quando utilizza un profilo di raccolta da un dispositivo connesso allo stesso Mac.

let email = "user@example.com"
logger.log("User login: \(email, privacy: .public)")

// Nei log di produzione: "User login: "
// Nel debug di Xcode: "User login: user@example.com"
logger.log("Payment token: \(token)")

Regole di privacy predefinite

I numeri (Int, Double, Float) sono considerati pubblici per impostazione predefinita — possono essere registrati in modo sicuro senza marcatura. Le stringhe (String, NSString, StaticString) e gli oggetti (NSObject, CFType) sono privati per impostazione predefinita — vengono mascherati in produzione. Le stringhe statiche (letterali di stringa tra virgolette all'interno della stringa di formato) sono sempre visibili — fanno parte del messaggio stesso, non dei dati.

Questo comportamento è diverso da NSLog, dove tutti i dati venivano registrati in testo semplice. Il passaggio a os_log riduce significativamente il rischio di fuga di dati sensibili degli utenti attraverso i log.

os_log vs NSLog: confronto delle prestazioni

os_log è dal 90 al 95% più veloce di NSLog nel logging ad alta frequenza. In un test con 10.000 chiamate in un ciclo, NSLog crea un ritardo di circa 2,8 secondi, mentre os_log esegue le stesse chiamate in 0,3 secondi. La differenza è spiegata dalle scritture sincrone su disco in NSLog rispetto alla bufferizzazione asincrona in os_log.

Secondo Apple Performance Lab (2016), un'applicazione iOS con 20 chiamate di logging al secondo tramite NSLog perde 5–8 fotogrammi di animazione al secondo a causa del blocco del thread principale. Con os_log non si verifica alcuna perdita di fotogrammi perché la bufferizzazione avviene in un thread separato del kernel.

Esempi di codice con os_log in Swift

os_log ha due API: la classica in C os_log_create e il wrapper moderno Swift Logger presentato in iOS 14. Lo Swift Logger utilizza il sistema ResultBuilder per la formattazione — gli argomenti vengono interpolati tramite letterali di stringa con marcatura esplicita della privacy.

import OSLog

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

func handleResponse(statusCode: Int) {
    if statusCode > 399 {
        logger.error("HTTP error: \(statusCode, privacy: .public)")
    } else {
        logger.info("Response OK: \(statusCode)")
    }
}

log collect è un'utilità a riga di comando per esportare i log raccolti da un dispositivo. Viene eseguita dal Terminale dopo aver collegato il dispositivo a un Mac tramite USB.

// Raccolta log in .logarchive
// Nel Terminale: log collect --device --output ./app_logs.logarchive
// Visualizzazione log subsystem: log show --subsystem com.example.app

// Logging con valori dinamici
logger.log("User \(userId) opened screen \(screenName)")

Quando si utilizza Logger, è importante ricordare che gli argomenti vengono interpolati tramite String Interpolation, non tramite stringhe di formato come nella versione C di os_log. Questo è più sicuro, ma richiede la marcatura esplicita della privacy per ogni argomento se il comportamento predefinito non è adatto allo sviluppatore.