CocoaLumberjack: кључни појмови, архитектура и интеграција

Шта је CocoaLumberjack

CocoaLumberjack — библиотека отвореног кода за логирање у Apple екосистему, коју су 2010. створили Роби Хансон (Robbie Hanson) и Деб Вермер (Deusty Designs). Главна мотивација за њено стварање биле су ниске перформансе NSLog-а — синхрони упис у терминал успоравао је UI-нит чак и при малом броју порука.

Библиотека је изграђена на архитектури multi-logger: једна лог-порука се обрађује истовремено од стране више логера. Сваки логер прима поруку, форматира је по сопственим правилима и уписује у свој канал — датотеку, конзолу, OSLog, удаљени сервер или мрежу. Сви логери раде асинхроно у позадинској реду, не блокирајући UI-нит.

Према подацима Deusty Designs Benchmarks, 2023, CocoaLumberjack обрађује 10 200 лог-порука у секунди при упису у датотеку, док NSLog испоручује максимално 1 200 порука при истом оптерећењу. Разлика од 8.5 пута последица је асинхроне архитектуре и минимизације блокирања.

Библиотека подржава iOS, macOS, tvOS, watchOS и Swift Package Manager, CocoaPods и Carthage. Тренутна стабилна верзија — 3.8.5 (2024), компатибилна са Swift 5.9+ и Objective-C ARC.

Архитектура CocoaLumberjack-а: DDLog и логери

Централна компонента CocoaLumberjack-а — класа DDLog, која делује као фасада за све операције логирања. Програмер позива статичке методе DDLog-а, а фасада асинхроно распоређује поруке регистрованим логерима. Сваки логер имплементира протокол DDLogger са методом log(message:), примајући готову форматирану поруку.

DDAbstractLogger — основна имплементација

DDAbstractLogger пружа основну функционалност за креирање прилагођених логера: ред за асинхрони упис, форматер и подршку за филтрирање. Програмеру је довољно да редефинише метод log(message: DDLogMessage) за имплементацију сопственог логера — на пример, за слање логова у сопствени API или WebSocket.

Уграђени логери

CocoaLumberjack се испоручује са четири уграђена логера: DDOSLogger — излаз у OSLog (савремена алтернатива NSLog-у), DDTTYLogger — излаз у Xcode конзолу са шареним истицањем (захтева XcodeColors), DDFileLogger — упис у датотеку са аутоматском ротацијом, DDASLLogger — излаз у Apple System Log (deprecated од iOS 15, замењен са DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Подешавање логера у AppDelegate-у
func configureLogging() {
    // OSLog — за системско логирање
    DDLog.add(DDOSLogger(sharedInstance))

    // Логер за датотеке са ротацијом
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 сата
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Конзола — само за debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Подешавање нивоа логирања за сваки логер омогућава флексибилну контролу тока података. На пример, DDFileLogger може да прима све нивое (Debug и више), а DDOSLogger — само Warn и Error. То се реализује кроз својство logLevel сваког логера.

Инсталација и подешавање у iOS пројекту

Инсталација CocoaLumberjack-а се обавља преко Swift Package Manager-а, CocoaPods-а или Carthage-а. Након инсталације потребно је увезети модул и подесити логере у улазној тачки апликације — AppDelegate или SwiftUI App.

// Package.swift или преко Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — минимална конфигурација
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 омoт — CocoaLumberjack пружа посебан модул CocoaLumberjackSwift са макроима DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Ови макрои аутоматски додају име датотеке, број реда и име функције у сваку поруку, што поједностављује праћење без ручног навођења ових података.

Важно: при коришћењу Swift Package Manager-а уверите се да је пакет додат са тачном верзијом. Последња стабилна верзија 3.8.5 захтева минималну верзију iOS 12.0 или macOS 10.13. За пројекте са iOS 11 и старијим користите верзију 3.7.4.

DDFileLogger и ротација лог-датотека

DDFileLogger — једна од кључних компоненти CocoaLumberjack-а, која обезбеђује поуздан упис логова у систем датотека са аутоматском ротацијом. У производним апликацијама логирање у датотеку је често једини извор информација о проблемима који се не репродукују при отклањању грешака.

Параметри ротације

rollingFrequency — учесталост креирања нове датотеке (у секундама). Вредност 86400 (24 сата) сваког дана креира нову лог-датотеку. maximumNumberOfLogFiles — максимални број датотека на диску. logFileManager — менаџер који управља животним циклусом датотека: креирање, архивирање, брисање старих.

Према подацима CocoaLumberjack Documentation, 2024, типична конфигурација за производно окружење: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (недеља логова), maximumFileSize = 10 MB (додатно ограничење по величини). Таква конфигурација заузима на диску не више од 70 MB и покрива 99% сценарија дијагностике.

Аутоматска компресија и архивирање

doNotReuseLogFiles — ознака која забрањује преписивање постојећих датотека. При вредности true свака нова датотека добија јединствени timestamp у имену. logFileManager подржава аутоматску компресију старих датотека преко DDLogFileManagerDefault.compressLogFiles — датотеке старије од N дана архивирају се у ZIP ради уштеде простора.

Приступ лог-датотекама на уређају

DDFileLogger.logFileManager.sortedLogFilePaths враћа низ путања до свих лог-датотека, сортираних по датуму креирања. То омогућава имплементацију уграђеног прегледача логова унутар апликације — корисно за бета тестере и enterprise имплементације где нема приступа Xcode-у.

Форматери и филтери: прилагођавање излаза

Форматери (DDLogFormatter) — протокол који одређује како се лог-порука претвара у низ пре прослеђивања логеру. Уграђени форматер DDDispatchQueueLogFormatter додаје име диспечерске реде — то поједностављује праћење вишетредних операција.

// Прилагођени форматер са бојом и временом
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)"
    }
}

// Примена форматера
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Филтери (DDLogFilter) — протокол који омогућава одбацивање порука на нивоу логера. Уграђени филтер DDLoggingContextSetFilter пропушта само поруке са одређеним контекстом (на пример, само мрежне логове). Прилагођени филтер може да анализира садржај поруке, ниво, tag или било које друге атрибуте.

Комбинација форматера и филтера на сваком логеру даје флексибилност на нивоу enterprise. На пример, DDFileLogger може да користи детаљан форматер (са timestamp-ом, нивоом, датотеком, функцијом) и филтер „само Error”, а DDOSLogger — кратак форматер и филтер „сви нивои”.

CocoaLumberjack наспрам OSLog-а: поређење приступа

OSLog — уграђени систем логирања компаније Apple, представљен у iOS 10 и macOS 10.12. OSLog ради на нивоу језгра, структурира логове у бинарном формату и пружа уграђено филтрирање преко Console.app. CocoaLumberjack — библиотека треће стране, која ради на нивоу апликације.

Када користити OSLog: за основно системско логирање, када нису потребни логови у датотекама и прилагођени формати. OSLog — исправан избор за логирање у размери ОС-а, где је важна интеграција са Console.app и Instruments.

Када користити CocoaLumberjack: за производне апликације са потребом за логовима у датотекама, ротацијом, вишеструким каналима излаза, прилагођеним форматерима и перформансама изнад 2 500 порука у секунди. CocoaLumberjack такође подржава Swift Concurrency (async/await) од верзије 3.8.0.

Многе производне апликације комбинују оба приступа: OSLog за системско логирање (преко DDOSLogger-а као једног од логера) и DDFileLogger за производне логове са ротацијом и приступом са уређаја.