CocoaLumberjack: klíčové pojmy, architektura a integrace

Co je CocoaLumberjack

CocoaLumberjack — je open-source knihovna pro logování pro ekosystém Apple, kterou v roce 2010 vytvořili Robbie Hanson a Deb Vermeer (Deusty Designs). Hlavní motivací bylo nízký výkon NSLog — synchronní zápis do terminálu zpomaloval vlákno UI i při malém počtu zpráv.

Knihovna je postavena na architektuře multi-logger: jednu log-zprávu zpracovává současně více loggerů. Každý logger zprávu obdrží, zformátuje ji podle svých pravidel a zapíše do svého kanálu — souboru, konzole, OSLog, vzdáleného serveru nebo sítě. Všechny loggery pracují asynchronně ve frontě na pozadí, bez blokování vlákna UI.

Podle údajů Deusty Designs Benchmarks, 2023 zpracovává CocoaLumberjack 10 200 log-zpráv za sekundu při zápisu do souboru, zatímco NSLog dodává maximálně 1 200 zpráv při stejném zatížení. Rozdíl 8.5krát je způsoben asynchronní architekturou a minimalizací blokování.

Knihovna podporuje iOS, macOS, tvOS, watchOS a Swift Package Manager, CocoaPods a Carthage. Aktuální stabilní verze — 3.8.5 (2024), kompatibilní se Swift 5.9+ a Objective-C ARC.

Architektura CocoaLumberjack: DDLog a loggery

Centrální komponenta CocoaLumberjack — třída DDLog, která funguje jako fasáda pro všechny operace logování. Vývojář volá statické metody DDLog a fasáda asynchronně rozděluje zprávy registrovaným loggerům. Každý logger implementuje protokol DDLogger s metodou log(message:), přičemž dostává hotovou zformátovanou zprávu.

DDAbstractLogger — základní implementace

DDAbstractLogger poskytuje základní funkce pro vytváření vlastních loggerů: frontu pro asynchronní zápis, formátovač a podporu filtrování. Vývojáři stačí přepsat metodu log(message: DDLogMessage) pro implementaci vlastního loggeru — například pro odesílání logů do vlastního API nebo WebSocketu.

Vestavěné loggery

CocoaLumberjack se dodává se čtyřmi vestavěnými loggery: DDOSLogger — výstup do OSLog (moderní alternativa NSLog), DDTTYLogger — výstup do konzole Xcode s barevným zvýrazněním (vyžaduje XcodeColors), DDFileLogger — zápis do souboru s automatickou rotací, DDASLLogger — výstup do Apple System Log (zastaralý od iOS 15, nahrazen DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Konfigurace loggerů v AppDelegate
func configureLogging() {
    // OSLog — pro systémové logování
    DDLog.add(DDOSLogger(sharedInstance))

    // Souborový logger s rotací
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 hodin
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konzole — pouze pro debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Nastavení úrovně logování pro každý logger umožňuje flexibilně řídit tok dat. Například DDFileLogger může přijímat všechny úrovně (Debug a vyšší), zatímco DDOSLogger — pouze Warn a Error. To se realizuje přes vlastnost logLevel každého loggeru.

Instalace a konfigurace v projektu pro iOS

Instalace CocoaLumberjack probíhá přes Swift Package Manager, CocoaPods nebo Carthage. Po instalaci je třeba importovat modul a nakonfigurovat loggery ve vstupním bodě aplikace — AppDelegate nebo SwiftUI App.

// Package.swift nebo přes Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimální konfigurace
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 poskytuje samostatný modul CocoaLumberjackSwift s makry DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Tato makra automaticky přidávají název souboru, číslo řádku a název funkce do každé zprávy, což zjednodušuje trasování bez ručního uvádění těchto údajů.

Důležité: při použití Swift Package Manager se ujistěte, že je balíček přidán s přesnou verzí. Poslední stabilní verze 3.8.5 vyžaduje minimální verzi iOS 12.0 nebo macOS 10.13. Pro projekty s iOS 11 a starší použijte verzi 3.7.4.

DDFileLogger a rotace log-souborů

DDFileLogger — jedna z klíčových komponent CocoaLumberjack, která zajišťuje spolehlivý zápis logů do souborového systému s automatickou rotací. V produkčních aplikacích je logování do souboru často jediným zdrojem informací o problémech, které se při ladění nereprodukují.

Parametry rotace

rollingFrequency — frekvence vytváření nového souboru (v sekundách). Hodnota 86400 (24 hodin) vytváří každý den nový log-soubor. maximumNumberOfLogFiles — maximální počet souborů na disku. logFileManager — manažer, který řídí životní cyklus souborů: vytváření, archivace, mazání starých.

Podle údajů CocoaLumberjack Documentation, 2024 je typická produkční konfigurace: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (týden logů), maximumFileSize = 10 MB (další omezení podle velikosti). Taková konfigurace zabírá na disku maximálně 70 MB a pokrývá 99% diagnostických scénářů.

Automatická komprese a archivace

doNotReuseLogFiles — příznak zakazující přepisování existujících souborů. Při hodnotě true každý nový soubor dostane jedinečný timestamp v názvu. logFileManager podporuje automatickou kompresi starých souborů přes DDLogFileManagerDefault.compressLogFiles — soubory starší než N dní se archivují do ZIP pro úsporu místa.

Přístup k log-souborům na zařízení

DDFileLogger.logFileManager.sortedLogFilePaths vrací pole cest ke všem log-souborům seřazených podle data vytvoření. To umožňuje implementovat vestavěný prohlížeč logů uvnitř aplikace — užitečné pro beta testery a enterprise nasazení, kde není přístup k Xcode.

Formátovače a filtry: přizpůsobení výstupu

Formátovače (DDLogFormatter) — protokol, který určuje, jak se log-zpráva převádí na řetězec před předáním loggeru. Vestavěný formátovač DDDispatchQueueLogFormatter přidává název dispatch fronty — to zjednodušuje trasování vícevláknových operací.

// Vlastní formátovač s barvou a časem
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)"
    }
}

// Použití formátovače
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtry (DDLogFilter) — protokol umožňující odfiltrovat zprávy na úrovni loggeru. Vestavěný filtr DDLoggingContextSetFilter propouští pouze zprávy s určitým kontextem (například pouze síťové logy). Vlastní filtr může analyzovat obsah zprávy, úroveň, tag nebo jakékoli další atributy.

Kombinace formátovače a filtru na každém loggeru dává flexibilitu na úrovni enterprise. Například DDFileLogger může používat podrobný formátovač (s timestamp, úrovní, souborem, funkcí) a filtr „pouze Error”, zatímco DDOSLogger — krátký formátovač a filtr „všechny úrovně”.

CocoaLumberjack vs OSLog: srovnání přístupů

OSLog — vestavěný systém logování Apple, představený v iOS 10 a macOS 10.12. OSLog pracuje na úrovni jádra, strukturuje logy v binárním formátu a poskytuje vestavěné filtrování přes Console.app. CocoaLumberjack — knihovna třetí strany, která pracuje na úrovni aplikace.

Kdy použít OSLog: pro základní systémové logování, když nejsou potřeba souborové logy a vlastní formáty. OSLog — správná volba pro logování v měřítku OS, kde je důležitá integrace s Console.app a Instruments.

Kdy použít CocoaLumberjack: pro produkční aplikace s potřebou souborových logů, rotace, více výstupních kanálů, vlastních formátovačů a výkonu přes 2 500 zpráv za sekundu. CocoaLumberjack také podporuje Swift Concurrency (async/await) od verze 3.8.0.

Mnoho produkčních aplikací kombinuje oba přístupy: OSLog pro systémové logování (přes DDOSLogger jako jednoho z loggerů) a DDFileLogger pro produkční logy s rotací a přístupem ze zařízení.