CocoaLumberjack: concetti chiave, architettura e integrazione

Cos'è CocoaLumberjack

CocoaLumberjack è una libreria di logging open source per l'ecosistema Apple creata da Robbie Hanson e Deusty Designs nel 2010. La motivazione principale era la scarsa prestazione di NSLog — la scrittura sincrona sul terminale rallentava il thread dell'interfaccia utente anche con un piccolo numero di messaggi.

La libreria è costruita su un'architettura multi-logger: un singolo messaggio di log viene elaborato da più logger contemporaneamente. Ogni logger riceve il messaggio, lo formatta secondo le proprie regole e lo scrive sul proprio canale — file, console, OSLog, server remoto o rete. Tutti i logger lavorano in modo asincrono in una coda in background, senza bloccare il thread dell'interfaccia utente.

Secondo Deusty Designs Benchmarks, 2023, CocoaLumberjack elabora 10.200 messaggi di log al secondo durante la scrittura su file, mentre NSLog fornisce al massimo 1.200 messaggi con lo stesso carico. La differenza di 8,5 volte è dovuta all'architettura asincrona e alla minimizzazione dei blocchi.

La libreria supporta iOS, macOS, tvOS, watchOS e Swift Package Manager, CocoaPods e Carthage. La versione stabile attuale è la 3.8.5 (2024), compatibile con Swift 5.9+ e Objective-C ARC.

Architettura di CocoaLumberjack: DDLog e logger

Il componente centrale di CocoaLumberjack è la classe DDLog, che funge da facade per tutte le operazioni di logging. Lo sviluppatore chiama i metodi statici di DDLog e la facade distribuisce in modo asincrono i messaggi ai logger registrati. Ogni logger implementa il protocollo DDLogger con il metodo log(message:), ricevendo un messaggio formattato pronto.

DDAbstractLogger — Implementazione base

DDAbstractLogger fornisce funzionalità di base per creare logger personalizzati: una coda per la scrittura asincrona, un formattatore e il supporto al filtraggio. Lo sviluppatore deve solo sovrascrivere il metodo log(message: DDLogMessage) per implementare il proprio logger — ad esempio, per inviare log a un'API personalizzata o WebSocket.

Logger integrati

CocoaLumberjack viene fornito con quattro logger integrati: DDOSLogger — output su OSLog (alternativa moderna a NSLog), DDTTYLogger — output sulla console di Xcode con evidenziazione a colori (richiede XcodeColors), DDFileLogger — scrittura su file con rotazione automatica, DDASLLogger — output su Apple System Log (deprecato da iOS 15, sostituito da DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Configurazione logger in AppDelegate
func configureLogging() {
    // OSLog — per logging di sistema
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger file con rotazione
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 ore
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Console — solo debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

La configurazione del livello di log per ogni logger consente un controllo flessibile del flusso di dati. Ad esempio, DDFileLogger può accettare tutti i livelli (Debug e superiori), mentre DDOSLogger solo Warn ed Error. Questo è implementato tramite la proprietà logLevel di ogni logger.

Installazione e configurazione in progetti iOS

L'installazione di CocoaLumberjack viene eseguita tramite Swift Package Manager, CocoaPods o Carthage. Dopo l'installazione, è necessario importare il modulo e configurare i logger nel punto di ingresso dell'applicazione — AppDelegate o SwiftUI App.

// Package.swift o tramite Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — configurazione minima
import UIKit
import CocoaLumberjack

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        application: UIApplication,
        didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        DDLog.add(DDOSLogger(sharedInstance))
        DDLogInfo("Logging configured successfully")
        return true
    }
}

Il wrapper Swift — CocoaLumberjack fornisce un modulo separato CocoaLumberjackSwift con le macro DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Queste macro aggiungono automaticamente il nome del file, il numero di riga e il nome della funzione a ogni messaggio, semplificando la tracciatura senza dover specificare manualmente questi dati.

Importante: quando si utilizza Swift Package Manager, assicurarsi di aggiungere il pacchetto con la versione esatta. L'ultima versione stabile 3.8.5 richiede almeno iOS 12.0 o macOS 10.13. Per progetti con iOS 11 e versioni precedenti, utilizzare la versione 3.7.4.

DDFileLogger e rotazione dei file di log

DDFileLogger è uno dei componenti chiave di CocoaLumberjack, che fornisce una scrittura affidabile dei log nel file system con rotazione automatica. Nelle applicazioni di produzione, la registrazione su file è spesso l'unica fonte di informazioni sui problemi che non possono essere riprodotti in fase di debug.

Parametri di rotazione

rollingFrequency — la frequenza di creazione di un nuovo file di log (in secondi). Un valore di 86400 (24 ore) crea un nuovo file di log ogni giorno. maximumNumberOfLogFiles — il numero massimo di file su disco. logFileManager — il gestore che controlla il ciclo di vita dei file: creazione, archiviazione, eliminazione dei file vecchi.

Secondo la Documentazione di CocoaLumberjack, 2024, una configurazione tipica per la produzione: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (una settimana di log), maximumFileSize = 10 MB (limite aggiuntivo di dimensione). Questa configurazione occupa non più di 70 MB su disco e copre il 99% degli scenari diagnostici.

Compressione e archiviazione automatiche

doNotReuseLogFiles — un flag che impedisce la sovrascrittura dei file esistenti. Quando impostato su true, ogni nuovo file riceve un timestamp unico nel suo nome. logFileManager supporta la compressione automatica dei file vecchi tramite DDLogFileManagerDefault.compressLogFiles — i file più vecchi di N giorni vengono archiviati in ZIP per risparmiare spazio.

Accesso ai file di log sul dispositivo

DDFileLogger.logFileManager.sortedLogFilePaths restituisce un array di percorsi a tutti i file di log ordinati per data di creazione. Ciò consente di implementare un visualizzatore di log integrato nell'app — utile per beta tester e distribuzioni aziendali dove non c'è accesso a Xcode.

Formattatori e filtri: personalizzazione dell'output

I formattatori (DDLogFormatter) — sono un protocollo che definisce come un messaggio di log viene trasformato in una stringa prima di essere passato al logger. Il formattatore integrato DDDispatchQueueLogFormatter aggiunge il nome della coda di dispatch — questo semplifica la tracciatura delle operazioni multi-thread.

// Formatter personalizzato con colore e ora
class CustomLogFormatter: NSObject, DDLogFormatter {

    private let dateFormatter: DateFormatter = {
        let fmt = DateFormatter()
        fmt.dateFormat = "yyyy-MM-dd HH:mm:ss.SSS"
        return fmt
    }()

    func format(message logMessage: DDLogMessage) -> String? {
        let timestamp = dateFormatter.string(
            from: logMessage.timestamp)
        let level = logMessage.level.name
        let file = (logMessage.file as NSString).lastPathComponent
        let line = logMessage.line

        return "[\(timestamp)] [\(level)] [\(file):\(line)] \(logMessage.message)"
    }
}

// Applicazione del formatter
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

I filtri (DDLogFilter) — sono un protocollo che consente di filtrare i messaggi a livello di logger. Il filtro integrato DDLoggingContextSetFilter fa passare solo i messaggi con un contesto specifico (ad esempio, solo log di rete). Un filtro personalizzato può analizzare il contenuto del messaggio, il livello, il tag o qualsiasi altro attributo.

Una combinazione di formattatore e filtro su ogni logger offre flessibilità a livello enterprise. Ad esempio, DDFileLogger può utilizzare un formattatore dettagliato (con timestamp, livello, file, funzione) e un filtro “solo Error”, mentre DDOSLogger utilizza un formattatore breve e un filtro “tutti i livelli”.

CocoaLumberjack vs OSLog: confronto degli approcci

OSLog è il sistema di logging integrato di Apple introdotto in iOS 10 e macOS 10.12. OSLog funziona a livello di kernel, struttura i log in formato binario e fornisce filtraggio integrato tramite Console.app. CocoaLumberjack è una libreria di terze parti che opera a livello di applicazione.

Quando usare OSLog: per il logging di sistema di base quando non sono necessari log su file e formati personalizzati. OSLog è la scelta giusta per il logging a livello di sistema operativo dove l'integrazione con Console.app e Instruments è importante.

Quando usare CocoaLumberjack: per applicazioni di produzione che necessitano di log su file, rotazione, canali di output multipli, formattatori personalizzati e prestazioni superiori a 2.500 messaggi al secondo. CocoaLumberjack supporta anche Swift Concurrency (async/await) a partire dalla versione 3.8.0.

Molte applicazioni di produzione combinano entrambi gli approcci: OSLog per il logging di sistema (tramite DDOSLogger come uno dei logger) e DDFileLogger per i log di produzione con rotazione e accesso dal dispositivo.