CocoaLumberjack: nyckelbegrepp, arkitektur och integrering

Vad är CocoaLumberjack

CocoaLumberjack — är ett öppen källkods-bibliotek för loggning inom Apples ekosystem, skapat av Robbie Hanson och Deb Vermeer (Deusty Designs) år 2010. Den främsta motivationen var NSLogs låga prestanda — synkron skrivning till terminalen saktade ner UI-tråden även vid ett litet antal meddelanden.

Biblioteket är byggt på multi-logger-arkitekturen: ett loggmeddelande bearbetas samtidigt av flera loggrar. Varje logger tar emot meddelandet, formaterar det enligt sina egna regler och skriver det till sin kanal — fil, konsol, OSLog, fjärrserver eller nätverk. Alla loggrar arbetar asynkront i bakgrundskön utan att blockera UI-tråden.

Enligt uppgifter från Deusty Designs Benchmarks, 2023 bearbetar CocoaLumberjack 10 200 loggmeddelanden per sekund vid skrivning till fil, medan NSLog levererar högst 1 200 meddelanden vid samma belastning. Skillnaden på 8.5 gånger beror på den asynkrona arkitekturen och minimeringen av blockeringar.

Biblioteket stöder iOS, macOS, tvOS, watchOS samt Swift Package Manager, CocoaPods och Carthage. Nuvarande stabila version — 3.8.5 (2024), kompatibel med Swift 5.9+ och Objective-C ARC.

CocoaLumberjacks arkitektur: DDLog och loggrar

Central komponent i CocoaLumberjack — klassen DDLog, som fungerar som fasad för alla loggningsoperationer. Utvecklaren anropar DDLogs statiska metoder, och fasaden distribuerar asynkront meddelanden till registrerade loggrar. Varje logger implementerar protokollet DDLogger med metoden log(message:), och får det färdigformaterade meddelandet.

DDAbstractLogger — grundimplementering

DDAbstractLogger tillhandahåller grundläggande funktionalitet för att skapa anpassade loggrar: en kö för asynkron skrivning, formatterare och stöd för filtrering. Det räcker att utvecklaren åsidosätter metoden log(message: DDLogMessage) för att implementera sin egen logger — till exempel för att skicka loggar till sitt eget API eller WebSocket.

Inbyggda loggrar

CocoaLumberjack levereras med fyra inbyggda loggrar: DDOSLogger — utdata till OSLog (modernt alternativ till NSLog), DDTTYLogger — utdata till Xcode-konsolen med färgmarkering (kräver XcodeColors), DDFileLogger — skrivning till fil med automatisk rotation, DDASLLogger — utdata till Apple System Log (utfasat från iOS 15, ersatt av DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Konfigurering av loggrar i AppDelegate
func configureLogging() {
    // OSLog — för systemloggning
    DDLog.add(DDOSLogger(sharedInstance))

    // Fillogger med rotation
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 timmar
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konsol — endast för debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Inställning av loggningsnivån för varje logger möjliggör flexibel kontroll av dataströmmen. Till exempel kan DDFileLogger acceptera alla nivåer (Debug och högre), medan DDOSLogger — endast Warn och Error. Detta implementeras via egenskapen logLevel hos varje logger.

Installation och konfigurering i ett iOS-projekt

Installation av CocoaLumberjack görs via Swift Package Manager, CocoaPods eller Carthage. Efter installationen måste modulen importeras och loggrarna konfigureras i appens startpunkt — AppDelegate eller SwiftUI App.

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

// AppDelegate.swift — minimal konfigurering
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 tillhandahåller en separat modul CocoaLumberjackSwift med makron DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Dessa makron lägger automatiskt till filnamnet, radnumret och funktionsnamnet i varje meddelande, vilket förenklar spårning utan att dessa uppgifter anges manuellt.

Viktigt: när du använder Swift Package Manager, se till att paketet läggs till med exakt version. Den senaste stabila versionen 3.8.5 kräver minst iOS 12.0 eller macOS 10.13. För projekt med iOS 11 och äldre, använd version 3.7.4.

DDFileLogger och rotation av loggfiler

DDFileLogger — en av de viktigaste komponenterna i CocoaLumberjack, som säkerställer tillförlitlig skrivning av loggar till filsystemet med automatisk rotation. I produktionsappar är filloggning ofta den enda informationskällan om problem som inte kan återskapas vid felsökning.

Rotationsparametrar

rollingFrequency — frekvensen för att skapa en ny fil (i sekunder). Värdet 86400 (24 timmar) skapar en ny loggfil varje dag. maximumNumberOfLogFiles — maximalt antal filer på disken. logFileManager — hanteraren som styr filernas livscykel: skapande, arkivering, radering av gamla.

Enligt uppgifter från CocoaLumberjack Documentation, 2024 är en typisk produktionskonfiguration: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (en vecka loggar), maximumFileSize = 10 MB (ytterligare storleksgräns). En sådan konfiguration tar högst 70 MB diskutrymme och täcker 99% av diagnostikscenarierna.

Automatisk komprimering och arkivering

doNotReuseLogFiles — en flagga som förbjuder överskrivning av befintliga filer. Vid värdet true får varje ny fil en unik timestamp i namnet. logFileManager stöder automatisk komprimering av gamla filer via DDLogFileManagerDefault.compressLogFiles — filer äldre än N dagar arkiveras i ZIP för att spara utrymme.

Åtkomst till loggfiler på enheten

DDFileLogger.logFileManager.sortedLogFilePaths returnerar en matris med sökvägar till alla loggfiler, sorterade efter skapelsedatum. Detta gör det möjligt att implementera en inbyggd loggvisare i appen — användbart för betatestare och enterprise-distributioner där det inte finns åtkomst till Xcode.

Formatterare och filter: anpassning av utdata

Formatterare (DDLogFormatter) — ett protokoll som definierar hur ett loggmeddelande omvandlas till en sträng innan det överförs till loggern. Den inbyggda formatteraren DDDispatchQueueLogFormatter lägger till namnet på dispatch-kön — detta förenklar spårning av flertrådade operationer.

// Anpassad formatterare med färg och tid
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)"
    }
}

// Tillämpning av formatteraren
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filter (DDLogFilter) — ett protokoll som gör det möjligt att filtrera bort meddelanden på loggernivå. Det inbyggda filtret DDLoggingContextSetFilter släpper bara igenom meddelanden med en viss kontext (till exempel endast nätverksloggar). Ett anpassat filter kan analysera meddelandets innehåll, nivå, tagg eller andra attribut.

Kombinationen av formatterare och filter på varje logger ger flexibilitet på företagsnivå. Till exempel kan DDFileLogger använda en detaljerad formatterare (med timestamp, nivå, fil, funktion) och filtret "endast Error", medan DDOSLogger — en kort formatterare och filtret "alla nivåer".

CocoaLumberjack vs OSLog: jämförelse av angreppssätt

OSLog — Apples inbyggda loggningssystem, introducerat i iOS 10 och macOS 10.12. OSLog arbetar på kärnnivå, strukturerar loggar i binärt format och tillhandahåller inbyggd filtrering via Console.app. CocoaLumberjack — är ett tredjepartsbibliotek som arbetar på appnivå.

När du ska använda OSLog: för grundläggande systemloggning, när filloggar och anpassade format inte behövs. OSLog är rätt val för loggning i operativsystems-skala, där integrering med Console.app och Instruments är viktig.

När du ska använda CocoaLumberjack: för produktionsappar med behov av filloggar, rotation, flera utdatakanaler, anpassade formatterare och prestanda över 2 500 meddelanden per sekund. CocoaLumberjack stöder även Swift Concurrency (async/await) från version 3.8.0.

Många produktionsappar kombinerar båda angreppssätten: OSLog för systemloggning (via DDOSLogger som en av loggrarna) och DDFileLogger för produktionsloggar med rotation och åtkomst från enheten.