CocoaLumberjack: kernbegrippen, architectuur en integratie

Wat is CocoaLumberjack

CocoaLumberjack — is een open-source loggingbibliotheek voor het Apple-ecosysteem, in 2010 gemaakt door Robbie Hanson en Deb Vermeer (Deusty Designs). De belangrijkste motivatie was de lage prestatie van NSLog — synchroon schrijven naar de terminal vertraagde de UI-thread zelfs bij een klein aantal berichten.

De bibliotheek is gebouwd op de multi-logger-architectuur: één logbericht wordt tegelijkertijd door meerdere loggers verwerkt. Elke logger ontvangt het bericht, formatteert het volgens eigen regels en schrijft het naar zijn kanaal — bestand, console, OSLog, externe server of netwerk. Alle loggers werken asynchroon in de achtergrondwachtrij, zonder de UI-thread te blokkeren.

Volgens gegevens van Deusty Designs Benchmarks, 2023 verwerkt CocoaLumberjack 10 200 logberichten per seconde bij het schrijven naar een bestand, terwijl NSLog maximaal 1 200 berichten levert bij dezelfde belasting. Het verschil van 8.5 keer is te danken aan de asynchrone architectuur en het minimaliseren van blokkades.

De bibliotheek ondersteunt iOS, macOS, tvOS, watchOS en Swift Package Manager, CocoaPods en Carthage. De huidige stabiele versie — 3.8.5 (2024), compatibel met Swift 5.9+ en Objective-C ARC.

Architectuur van CocoaLumberjack: DDLog en loggers

De centrale component van CocoaLumberjack — de klasse DDLog, die fungeert als facade voor alle loggingbewerkingen. De ontwikkelaar roept statische methoden van DDLog aan, en de facade verdeelt de berichten asynchroon over geregistreerde loggers. Elke logger implementeert het protocol DDLogger met de methode log(message:), en ontvangt het kant-en-klare geformatteerde bericht.

DDAbstractLogger — basisimplementatie

DDAbstractLogger biedt de basisfunctionaliteit voor het maken van aangepaste loggers: een wachtrij voor asynchroon schrijven, een formatteerder en ondersteuning voor filteren. De ontwikkelaar hoeft alleen de methode log(message: DDLogMessage) te overschrijven om zijn eigen logger te implementeren — bijvoorbeeld om logs naar zijn eigen API of WebSocket te sturen.

Ingebouwde loggers

CocoaLumberjack wordt geleverd met vier ingebouwde loggers: DDOSLogger — uitvoer naar OSLog (modern alternatief voor NSLog), DDTTYLogger — uitvoer naar de Xcode-console met kleurenmarkering (vereist XcodeColors), DDFileLogger — schrijven naar een bestand met automatische rotatie, DDASLLogger — uitvoer naar Apple System Log (verouderd vanaf iOS 15, vervangen door DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Loggers configureren in AppDelegate
func configureLogging() {
    // OSLog — voor systeemlogging
    DDLog.add(DDOSLogger(sharedInstance))

    // Bestandslogger met rotatie
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 uur
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

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

Het logniveau instellen voor elke logger maakt flexibele controle over de datastroom mogelijk. Zo kan DDFileLogger alle niveaus accepteren (Debug en hoger), terwijl DDOSLogger alleen Warn en Error accepteert. Dit wordt gerealiseerd via de eigenschap logLevel van elke logger.

Installatie en configuratie in een iOS-project

Installatie van CocoaLumberjack gebeurt via Swift Package Manager, CocoaPods of Carthage. Na installatie moet het module worden geïmporteerd en de loggers worden geconfigureerd op het instapunt van de app — AppDelegate of SwiftUI App.

// Package.swift of via Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimale configuratie
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
    }
}

Swift-wrapper — CocoaLumberjack biedt een aparte module CocoaLumberjackSwift met de macro's DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Deze macro's voegen automatisch de bestandsnaam, het regelnummer en de functienaam toe aan elk bericht, wat tracing vereenvoudigt zonder deze gegevens handmatig op te geven.

Belangrijk: zorg bij gebruik van Swift Package Manager dat het pakket met de exacte versie is toegevoegd. De nieuwste stabiele versie 3.8.5 vereist minimaal iOS 12.0 of macOS 10.13. Gebruik voor projecten met iOS 11 en ouder versie 3.7.4.

DDFileLogger en rotatie van logbestanden

DDFileLogger — een van de belangrijkste componenten van CocoaLumberjack, die betrouwbaar schrijven van logs naar het bestandssysteem met automatische rotatie garandeert. In productie-apps is bestandslogging vaak de enige informatiebron over problemen die niet reproduceerbaar zijn tijdens het debuggen.

Rotatieparameters

rollingFrequency — de frequentie waarmee een nieuw bestand wordt gemaakt (in seconden). De waarde 86400 (24 uur) maakt elke dag een nieuw logbestand aan. maximumNumberOfLogFiles — het maximale aantal bestanden op schijf. logFileManager — de manager die de levenscyclus van bestanden beheert: maken, archiveren, oude verwijderen.

Volgens gegevens van CocoaLumberjack Documentation, 2024 is een typische productieconfiguratie: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (een week logs), maximumFileSize = 10 MB (extra limiet op grootte). Zo'n configuratie neemt maximaal 70 MB schijfruimte in en dekt 99% van de diagnosesscenario's.

Automatische compressie en archivering

doNotReuseLogFiles — een vlag die overschrijven van bestaande bestanden verbiedt. Bij waarde true krijgt elk nieuw bestand een unieke timestamp in de naam. logFileManager ondersteunt automatische compressie van oude bestanden via DDLogFileManagerDefault.compressLogFiles — bestanden ouder dan N dagen worden gearchiveerd in ZIP om ruimte te besparen.

Toegang tot logbestanden op het apparaat

DDFileLogger.logFileManager.sortedLogFilePaths retourneert een array van paden naar alle logbestanden, gesorteerd op aanmaakdatum. Dit maakt het mogelijk een ingebouwde logviewer in de app te implementeren — handig voor bètatesters en enterprise-implementaties waar geen toegang is tot Xcode.

Formatteerders en filters: uitvoer aanpassen

Formatteerders (DDLogFormatter) — een protocol dat bepaalt hoe een logbericht wordt omgezet in een tekenreeks vóór overdracht aan de logger. De ingebouwde formatteerder DDDispatchQueueLogFormatter voegt de naam van de dispatch-wachtrij toe — dit vereenvoudigt het traceren van multithreaded bewerkingen.

// Aangepaste formatteerder met kleur en tijd
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)"
    }
}

// Formatteerder toepassen
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filters (DDLogFilter) — een protocol waarmee berichten op loggerniveau kunnen worden afgewezen. De ingebouwde filter DDLoggingContextSetFilter laat alleen berichten met een bepaalde context door (bijvoorbeeld alleen netwerklogs). Een aangepaste filter kan de inhoud van het bericht, het niveau, de tag of andere kenmerken analyseren.

De combinatie van een formatteerder en een filter op elke logger geeft flexibiliteit op enterprise-niveau. Zo kan DDFileLogger een gedetailleerde formatteerder (met timestamp, niveau, bestand, functie) en een filter „alleen Error” gebruiken, en DDOSLogger — een korte formatteerder en een filter „alle niveaus”.

CocoaLumberjack vs OSLog: benaderingen vergeleken

OSLog — het ingebouwde logging-systeem van Apple, geïntroduceerd in iOS 10 en macOS 10.12. OSLog werkt op kernelniveau, structureert logs in binair formaat en biedt ingebouwde filtering via Console.app. CocoaLumberjack — is een bibliotheek van derden die op appniveau werkt.

Wanneer OSLog gebruiken: voor basis-systeemlogging, wanneer bestandlogs en aangepaste formaten niet nodig zijn. OSLog is de juiste keuze voor logging op OS-schaal, waar integratie met Console.app en Instruments belangrijk is.

Wanneer CocoaLumberjack gebruiken: voor productie-apps met behoefte aan bestandlogs, rotatie, meerdere uitvoerkanalen, aangepaste formatteerders en prestaties boven 2 500 berichten per seconde. CocoaLumberjack ondersteunt ook Swift Concurrency (async/await) vanaf versie 3.8.0.

Veel productie-apps combineren beide benaderingen: OSLog voor systeemlogging (via DDOSLogger als een van de loggers) en DDFileLogger voor productielogs met rotatie en toegang vanaf het apparaat.