CocoaLumberjack: concepte cheie, arhitectură și integrare

Ce este CocoaLumberjack

CocoaLumberjack — este o bibliotecă open-source de logare pentru ecosistemul Apple, creată de Robbie Hanson și Deb Vermeer (Deusty Designs) în 2010. Principala motivație a fost performanța scăzută a NSLog — scrierea sincronă în terminal încetinea firul UI chiar și la un număr mic de mesaje.

Biblioteca este construită pe arhitectura multi-logger: un mesaj de log este procesat simultan de mai mulți loggeri. Fiecare logger primește mesajul, îl formatează după propriile reguli și îl scrie în canalul său — fișier, consolă, OSLog, server la distanță sau rețea. Toți loggerii lucrează asincron în coada de fundal, fără a bloca firul UI.

Conform datelor Deusty Designs Benchmarks, 2023, CocoaLumberjack procesează 10 200 de mesaje de log pe secundă la scrierea în fișier, în timp ce NSLog livrează maximum 1 200 de mesaje la aceeași sarcină. Diferența de 8.5 ori se datorează arhitecturii asincrone și minimizării blocajelor.

Biblioteca suportă iOS, macOS, tvOS, watchOS și Swift Package Manager, CocoaPods și Carthage. Versiunea stabilă actuală — 3.8.5 (2024), compatibilă cu Swift 5.9+ și Objective-C ARC.

Arhitectura CocoaLumberjack: DDLog și loggeri

Componenta centrală a CocoaLumberjack — clasa DDLog, care acționează ca fațadă pentru toate operațiile de logare. Dezvoltatorul apelează metodele statice DDLog, iar fațada distribuie asincron mesajele către loggerii înregistrați. Fiecare logger implementează protocolul DDLogger cu metoda log(message:), primind mesajul formatat gata.

DDAbstractLogger — implementarea de bază

DDAbstractLogger oferă funcționalitatea de bază pentru crearea loggerilor personalizați: coada pentru scrierea asincronă, formatterul și suportul pentru filtrare. Dezvoltatorului îi este suficient să suprascrie metoda log(message: DDLogMessage) pentru a implementa propriul logger — de exemplu, pentru a trimite logurile către propriul API sau WebSocket.

Loggerii încorporați

CocoaLumberjack vine cu patru loggeri încorporați: DDOSLogger — ieșire în OSLog (alternativa modernă la NSLog), DDTTYLogger — ieșire în consola Xcode cu evidențiere colorată (necesită XcodeColors), DDFileLogger — scriere în fișier cu rotație automată, DDASLLogger — ieșire în Apple System Log (depreciat începând cu iOS 15, înlocuit cu DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Configurarea loggerilor în AppDelegate
func configureLogging() {
    // OSLog — pentru logarea de sistem
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger de fișier cu rotație
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 de ore
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Consolă — doar pentru debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Setarea nivelului de logare pentru fiecare logger permite controlul flexibil al fluxului de date. De exemplu, DDFileLogger poate accepta toate nivelurile (Debug și mai sus), iar DDOSLogger — doar Warn și Error. Acest lucru se realizează prin proprietatea logLevel a fiecărui logger.

Instalarea și configurarea în proiectul iOS

Instalarea CocoaLumberjack se face prin Swift Package Manager, CocoaPods sau Carthage. După instalare, trebuie să importați modulul și să configurați loggerii în punctul de intrare al aplicației — AppDelegate sau SwiftUI App.

// Package.swift sau prin Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — configurare minimă
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
    }
}

Wrapper-ul Swift — CocoaLumberjack oferă un modul separat CocoaLumberjackSwift cu macrocomenzi DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Aceste macrocomenzi adaugă automat numele fișierului, numărul liniei și numele funcției în fiecare mesaj, simplificând urmărirea fără specificarea manuală a acestor date.

Important: când folosiți Swift Package Manager, asigurați-vă că pachetul este adăugat cu versiunea exactă. Ultima versiune stabilă 3.8.5 necesită versiunea minimă iOS 12.0 sau macOS 10.13. Pentru proiecte cu iOS 11 și mai vechi folosiți versiunea 3.7.4.

DDFileLogger și rotația fișierelor de log

DDFileLogger — una dintre componentele-cheie ale CocoaLumberjack, care asigură scrierea fiabilă a logurilor în sistemul de fișiere cu rotație automată. În aplicațiile de producție, logarea în fișier este adesea singura sursă de informații despre probleme care nu se reproduc în debugging.

Parametrii rotației

rollingFrequency — frecvența creării unui fișier nou (în secunde). Valoarea 86400 (24 de ore) creează un fișier de log nou în fiecare zi. maximumNumberOfLogFiles — numărul maxim de fișiere pe disc. logFileManager — managerul care controlează ciclul de viață al fișierelor: creare, arhivare, ștergerea celor vechi.

Conform datelor CocoaLumberjack Documentation, 2024, configurația tipică pentru producție: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (o săptămână de loguri), maximumFileSize = 10 MB (restricție suplimentară de dimensiune). O astfel de configurație ocupă pe disc nu mai mult de 70 MB și acoperă 99% din scenariile de diagnosticare.

Comprimarea și arhivarea automată

doNotReuseLogFiles — un indicator care interzice suprascrierea fișierelor existente. La valoarea true, fiecare fișier nou primește un timestamp unic în nume. logFileManager suportă comprimarea automată a fișierelor vechi prin DDLogFileManagerDefault.compressLogFiles — fișierele mai vechi de N zile sunt arhivate în ZIP pentru economisirea spațiului.

Accesul la fișierele de log de pe dispozitiv

DDFileLogger.logFileManager.sortedLogFilePaths returnează o matrice de căi către toate fișierele de log, sortate după data creării. Acest lucru permite implementarea unui vizualizator de loguri încorporat în aplicație — util pentru beta-testeri și implementările enterprise unde nu există acces la Xcode.

Formattere și filtre: personalizarea ieșirii

Formatterele (DDLogFormatter) — un protocol care definește cum este transformat mesajul de log într-un șir înainte de a fi transmis loggerului. Formatterul încorporat DDDispatchQueueLogFormatter adaugă numele cozii de dispatch — acest lucru simplifică urmărirea operațiilor multithreaded.

// Formatter personalizat cu culoare și timp
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)"
    }
}

// Aplicarea formatterului
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtrele (DDLogFilter) — un protocol care permite eliminarea mesajelor la nivelul loggerului. Filtrul încorporat DDLoggingContextSetFilter lasă să treacă doar mesajele cu un anumit context (de exemplu, doar logurile de rețea). Un filtru personalizat poate analiza conținutul mesajului, nivelul, tag-ul sau alte atribute.

Combinația de formatter și filtru pe fiecare logger oferă flexibilitate la nivel enterprise. De exemplu, DDFileLogger poate folosi un formatter detaliat (cu timestamp, nivel, fișier, funcție) și filtrul „doar Error”, iar DDOSLogger — un formatter scurt și filtrul „toate nivelurile”.

CocoaLumberjack vs OSLog: comparația abordărilor

OSLog — sistemul de logare integrat al Apple, introdus în iOS 10 și macOS 10.12. OSLog funcționează la nivel de kernel, structurează logurile în format binar și oferă filtrare integrată prin Console.app. CocoaLumberjack — este o bibliotecă terță, care funcționează la nivelul aplicației.

Când să folosiți OSLog: pentru logarea de bază de sistem, când nu sunt necesare loguri în fișier și formate personalizate. OSLog este alegerea corectă pentru logarea la scara OS, unde este importantă integrarea cu Console.app și Instruments.

Când să folosiți CocoaLumberjack: pentru aplicații de producție cu nevoia de loguri în fișier, rotație, canale multiple de ieșire, formattere personalizate și performanță de peste 2 500 de mesaje pe secundă. CocoaLumberjack suportă, de asemenea, Swift Concurrency (async/await) începând cu versiunea 3.8.0.

Multe aplicații de producție combină ambele abordări: OSLog pentru logarea de sistem (prin DDOSLogger ca unul dintre loggeri) și DDFileLogger pentru logurile de producție cu rotație și acces de pe dispozitiv.