CocoaLumberjack: kulcsfogalmak, architektúra és integráció

Mi az a CocoaLumberjack

CocoaLumberjack — nyílt forráskódú naplózási könyvtár az Apple ökoszisztémájához, amelyet Robbie Hanson és Deb Vermeer (Deusty Designs) hozott létre 2010-ben. A létrehozás fő motivációja a NSLog alacsony teljesítménye volt — a terminálba történő szinkron írás már kis üzenetszám mellett is lassította az UI-szálat.

A könyvtár a multi-logger architektúrára épül: egy naplóüzenetet egyszerre több logger dolgoz fel. Minden logger megkapja az üzenetet, saját szabályai szerint formázza, és a saját csatornájába írja — fájlba, konzolra, OSLog-ba, távoli szerverre vagy hálózatra. Minden logger aszinkron, háttérsorban dolgozik, anélkül hogy blokkolná az UI-szálat.

A Deusty Designs Benchmarks, 2023 adatai szerint a CocoaLumberjack fájlba íráskor 10 200 naplóüzenetet dolgoz fel másodpercenként, míg a NSLog ugyanekkora terhelés mellett maximum 1 200 üzenetet szállít. A 8.5-szeres különbség az aszinkron architektúrának és a blokkolások minimalizálásának köszönhető.

A könyvtár támogatja az iOS, macOS, tvOS, watchOS platformokat, valamint a Swift Package Manager, CocoaPods és Carthage csomagkezelőket. A jelenlegi stabil verzió — 3.8.5 (2024), kompatibilis a Swift 5.9+ és az Objective-C ARC rendszerrel.

A CocoaLumberjack architektúrája: DDLog és loggerek

Központi komponens a CocoaLumberjack-ban — a DDLog osztály, amely fasadként működik minden naplózási művelethez. A fejlesztő a DDLog statikus metódusait hívja meg, a fasad pedig aszinkron módon osztja szét az üzeneteket a regisztrált loggerek között. Minden logger a DDLogger protokollt implementálja a log(message:) metódussal, és a kész, formázott üzenetet kapja.

DDAbstractLogger — alapimplementáció

DDAbstractLogger alapfunkciót biztosít az egyedi loggerek létrehozásához: aszinkron íráshoz sort, formattert és szűrési támogatást. A fejlesztőnek elegendő felülírnia a log(message: DDLogMessage) metódust a saját logger implementálásához — például a naplók saját API-ba vagy WebSocket-re küldéséhez.

Beépített loggerek

A CocoaLumberjack négy beépített loggerrel érkezik: DDOSLogger — kimenet az OSLog-ba (a NSLog modern alternatívája), DDTTYLogger — kimenet az Xcode konzoljára színes kiemeléssel (XcodeColors-t igényel), DDFileLogger — írás fájlba automatikus rotációval, DDASLLogger — kimenet az Apple System Log-ba (az iOS 15-től deprecated, a DDOSLogger váltotta fel).

import CocoaLumberjack
import CocoaLumberjackSwift

// Loggerek konfigurálása az AppDelegate-ben
func configureLogging() {
    // OSLog — a rendszernaplózáshoz
    DDLog.add(DDOSLogger(sharedInstance))

    // Fájl-logger rotációval
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 óra
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konzol — csak debug-hoz
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

A naplózási szint beállítása minden logger esetében rugalmas adatfolyam-szabályozást tesz lehetővé. Például a DDFileLogger minden szintet elfogadhat (Debug és felette), a DDOSLogger viszont csak a Warn és Error szinteket. Ez az egyes loggerek logLevel tulajdonságán keresztül valósul meg.

Telepítés és konfigurálás iOS-projektben

Telepítés a CocoaLumberjack esetében a Swift Package Manager, CocoaPods vagy Carthage segítségével történik. Telepítés után importálni kell a modult, és konfigurálni a loggereket az alkalmazás belépési pontján — az AppDelegate-ben vagy a SwiftUI App-ban.

// Package.swift vagy az Xcode SPM-en keresztül
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimális konfiguráció
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 — a CocoaLumberjack külön CocoaLumberjackSwift modult kínál a DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose makrókkal. Ezek a makrók automatikusan hozzáadják a fájlnevet, a sorszámot és a függvénynevet minden üzenethez, ami leegyszerűsíti a nyomkövetést anélkül, hogy ezeket az adatokat kézzel kellene megadni.

Fontos: a Swift Package Manager használatakor győződjön meg arról, hogy a csomag pontos verzióval került hozzáadásra. A legújabb stabil verzió, a 3.8.5 legalább iOS 12.0 vagy macOS 10.13 verziót igényel. Az iOS 11 és régebbi projektekhez a 3.7.4 verziót használja.

DDFileLogger és a naplófájlok rotációja

DDFileLogger — a CocoaLumberjack egyik kulcskomponense, amely a naplók megbízható fájlrendszerbe írását automatikus rotációval biztosítja. Production-alkalmazásokban a fájlnaplózás gyakran az egyetlen információforrás a hibakeresés során reprodukálhatatlan problémákról.

A rotáció paraméterei

rollingFrequency — az új fájl létrehozásának gyakorisága (másodpercben). A 86400 (24 óra) érték minden nap új naplófájlt hoz létre. maximumNumberOfLogFiles — a lemezen lévő fájlok maximális száma. logFileManager — a fájlok életciklusát kezelő menedzser: létrehozás, archiválás, régiek törlése.

A CocoaLumberjack Documentation, 2024 adatai szerint a production-tipikus konfiguráció: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (egy hét napló), maximumFileSize = 10 MB (további méretkorlát). Ez a konfiguráció legfeljebb 70 MB lemezterületet foglal, és a diagnosztikai forgatókönyvek 99%-át lefedi.

Automatikus tömörítés és archiválás

doNotReuseLogFiles — egy jelző, amely tiltja a meglévő fájlok felülírását. True értéknél minden új fájl egyedi timestamp-et kap a nevében. logFileManager támogatja a régi fájlok automatikus tömörítését a DDLogFileManagerDefault.compressLogFiles segítségével — az N napnál régebbi fájlokat ZIP-be archiválja a helytakarékosság érdekében.

Hozzáférés a naplófájlokhoz az eszközön

DDFileLogger.logFileManager.sortedLogFilePaths az összes naplófájl elérési útjainak tömbjét adja vissza, létrehozási dátum szerint rendezve. Ez lehetővé teszi a beépített naplómegjelenítő implementálását az alkalmazáson belül — hasznos a béta-tesztelők és az enterprise-telepítések számára, ahol nincs hozzáférés az Xcode-hoz.

Formatterek és szűrők: a kimenet testreszabása

Formatterek (DDLogFormatter) — egy protokoll, amely meghatározza, hogyan alakul át a naplóüzenet karakterlánccá a loggernek való átadás előtt. A beépített DDDispatchQueueLogFormatter formatter hozzáadja a dispatch-sor nevét — ez leegyszerűsíti a több szálon futó műveletek nyomkövetését.

// Egyedi formatter színnel és idővel
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)"
    }
}

// A formatter alkalmazása
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Szűrők (DDLogFilter) — egy protokoll, amely lehetővé teszi az üzenetek logger-szintű kiszűrését. A beépített DDLoggingContextSetFilter szűrő csak a meghatározott kontextusú üzeneteket engedi át (például csak a hálózati naplókat). Az egyedi szűrő elemezheti az üzenet tartalmát, szintjét, tag-jét vagy bármely más attribútumát.

A formatter és a szűrő kombinációja minden loggeren enterprise-szintű rugalmasságot ad. Például a DDFileLogger részletes formattert (timestamp-pel, szinttel, fájllal, függvénnyel) és „csak Error” szűrőt használhat, a DDOSLogger pedig — rövid formattert és „minden szint” szűrőt.

CocoaLumberjack vs OSLog: a megközelítések összehasonlítása

OSLog — az Apple beépített naplózási rendszere, amely az iOS 10-ben és a macOS 10.12-ben jelent meg. Az OSLog kernelszinten működik, bináris formátumban strukturálja a naplókat, és beépített szűrést biztosít a Console.app-on keresztül. A CocoaLumberjack — harmadik féltől származó könyvtár, amely az alkalmazás szintjén működik.

Mikor használja az OSLog-ot: alapvető rendszernaplózáshoz, amikor nincs szükség fájlnaplókra és egyedi formátumokra. Az OSLog a megfelelő választás az operációs rendszer léptékű naplózáshoz, ahol fontos a Console.app-pal és az Instruments-szel való integráció.

Mikor használja a CocoaLumberjack-ot: production-alkalmazásokhoz, amelyeknek fájlnaplókra, rotációra, több kimeneti csatornára, egyedi formatterekre és másodpercenként több mint 2 500 üzenet teljesítményére van szükségük. A CocoaLumberjack a 3.8.0 verziótól kezdve a Swift Concurrency (async/await) támogatását is kínálja.

Számos production-alkalmazás kombinálja a két megközelítést: az OSLog-ot a rendszernaplózáshoz (a DDOSLogger-en keresztül az egyik loggerként) és a DDFileLogger-t a production-naplókhoz, rotációval és az eszközről való hozzáféréssel.