CocoaLumberjack: kluczowe pojęcia, architektura i integracja

Czym jest CocoaLumberjack

CocoaLumberjack — to biblioteka logowania open-source dla ekosystemu Apple, stworzona przez Robbiego Hansona (Robbie Hanson) i Deba Vermeera (Deusty Designs) w 2010 roku. Główną motywacją było niskie wydajność NSLog — synchroniczny zapis do terminala spowalniał wątek UI nawet przy niewielkiej liczbie komunikatów.

Biblioteka jest zbudowana na architekturze multi-logger: jeden komunikat logu jest przetwarzany jednocześnie przez kilka loggerów. Każdy logger otrzymuje komunikat, formatuje go według własnych zasad i zapisuje w swoim kanale — pliku, konsoli, OSLog, zdalnym serwerze lub sieci. Wszystkie loggery działają asynchronicznie w kolejce w tle, nie blokując wątku UI.

Według danych Deusty Designs Benchmarks, 2023, CocoaLumberjack przetwarza 10 200 komunikatów logów na sekundę przy zapisie do pliku, podczas gdy NSLog osiąga maksymalnie 1 200 komunikatów przy tym samym obciążeniu. Różnica 8.5 razy wynika z asynchronicznej architektury i minimalizacji blokad.

Biblioteka obsługuje iOS, macOS, tvOS, watchOS oraz Swift Package Manager, CocoaPods i Carthage. Aktualna stabilna wersja — 3.8.5 (2024), zgodna ze Swift 5.9+ i Objective-C ARC.

Architektura CocoaLumberjack: DDLog i loggery

Centralny komponent CocoaLumberjack — to klasa DDLog, pełniąca rolę fasady dla wszystkich operacji logowania. Deweloper wywołuje statyczne metody DDLog, a fasada asynchronicznie rozdziela komunikaty między zarejestrowane loggery. Każdy logger implementuje protokół DDLogger z metodą log(message:), otrzymując gotowy sformatowany komunikat.

DDAbstractLogger — podstawowa implementacja

DDAbstractLogger zapewnia podstawową funkcjonalność do tworzenia niestandardowych loggerów: kolejkę do asynchronicznego zapisu, format i obsługę filtrowania. Deweloperowi wystarczy nadpisać metodę log(message: DDLogMessage), aby zaimplementować własny logger — na przykład do wysyłania logów do własnego API lub WebSocket.

Wbudowane loggery

CocoaLumberjack jest dostarczany z czterema wbudowanymi loggerami: DDOSLogger — zapis do OSLog (nowoczesna alternatywa dla NSLog), DDTTYLogger — zapis do konsoli Xcode z kolorowym podświetleniem (wymaga XcodeColors), DDFileLogger — zapis do pliku z automatyczną rotacją, DDASLLogger — zapis do Apple System Log (zdeprecjonowany od iOS 15, zastąpiony przez DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Konfiguracja loggerów w AppDelegate
func configureLogging() {
    // OSLog — do logowania systemowego
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger plikowy z rotacją
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 godziny
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konsola — tylko do debugowania
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Ustawienie poziomu logowania dla każdego loggera pozwala elastycznie kontrolować przepływ danych. Na przykład DDFileLogger może przyjmować wszystkie poziomy (Debug i wyższe), a DDOSLogger — tylko Warn i Error. Realizuje się to przez właściwość logLevel każdego loggera.

Instalacja i konfiguracja w projekcie iOS

Instalacja CocoaLumberjack odbywa się przez Swift Package Manager, CocoaPods lub Carthage. Po instalacji należy zaimportować moduł i skonfigurować loggery w punkcie wejścia aplikacji — AppDelegate lub SwiftUI App.

// Package.swift lub przez Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimalna konfiguracja
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 Swift — CocoaLumberjack udostępnia osobny moduł CocoaLumberjackSwift z makrami DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Te makra automatycznie dodają nazwę pliku, numer wiersza i nazwę funkcji do każdego komunikatu, co upraszcza śledzenie bez ręcznego podawania tych danych.

Ważne: podczas korzystania z Swift Package Manager upewnij się, że dodano pakiet z dokładną wersją. Ostatnia stabilna wersja 3.8.5 wymaga minimalnej wersji iOS 12.0 lub macOS 10.13. Dla projektów z iOS 11 i starszych użyj wersji 3.7.4.

DDFileLogger i rotacja plików logów

DDFileLogger — to jeden z kluczowych komponentów CocoaLumberjack, zapewniający niezawodny zapis logów do systemu plików z automatyczną rotacją. W aplikacjach produkcyjnych logowanie plikowe jest często jedynym źródłem informacji o problemach, których nie da się odtworzyć podczas debugowania.

Parametry rotacji

rollingFrequency — częstotliwość tworzenia nowego pliku (w sekundach). Wartość 86400 (24 godziny) tworzy nowy plik logu codziennie. maximumNumberOfLogFiles — maksymalna liczba plików na dysku. logFileManager — menedżer zarządzający cyklem życia plików: tworzenie, archiwizacja, usuwanie starych.

Według danych CocoaLumberjack Documentation, 2024, typowa konfiguracja produkcyjna: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (tydzień logów), maximumFileSize = 10 MB (dodatkowe ograniczenie rozmiaru). Taka konfiguracja zajmuje na dysku nie więcej niż 70 MB i pokrywa 99% scenariuszy diagnostycznych.

Automatyczna kompresja i archiwizacja

doNotReuseLogFiles — flaga zabraniająca nadpisywania istniejących plików. Przy wartości true każdy nowy plik otrzymuje unikalny timestamp w nazwie. logFileManager obsługuje automatyczną kompresję starych plików przez DDLogFileManagerDefault.compressLogFiles — pliki starsze niż N dni są archiwizowane do ZIP w celu oszczędności miejsca.

Dostęp do plików logów na urządzeniu

DDFileLogger.logFileManager.sortedLogFilePaths zwraca tablicę ścieżek do wszystkich plików logów, posortowanych według daty utworzenia. Pozwala to zaimplementować wbudowany podgląd logów wewnątrz aplikacji — przydatny dla beta-testerów i wdrożeń enterprise, gdzie nie ma dostępu do Xcode.

Formatty i filtry: personalizacja wyników

Formatty (DDLogFormatter) — to protokół określający, jak komunikat logu jest przekształcany w ciąg znaków przed przekazaniem loggerowi. Wbudowany format DDDispatchQueueLogFormatter dodaje nazwę kolejki wysyłania — upraszcza to śledzenie operacji wielowątkowych.

// Niestandardowy format z kolorem i czasem
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)"
    }
}

// Zastosowanie formatu
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtry (DDLogFilter) — to protokół pozwalający odfiltrowywać komunikaty na poziomie loggera. Wbudowany filtr DDLoggingContextSetFilter przepuszcza tylko komunikaty z określonym kontekstem (na przykład tylko logi network). Niestandardowy filtr może analizować zawartość komunikatu, poziom, tag lub inne atrybuty.

Połączenie formatu i filtra na każdym loggerze daje elastyczność na poziomie enterprise. Na przykład DDFileLogger może używać szczegółowego formatu (z timestamp, poziomem, plikiem, funkcją) i filtra „tylko Error”, a DDOSLogger — krótkiego formatu i filtra „wszystkie poziomy”.

CocoaLumberjack vs OSLog: porównanie podejść

OSLog — to wbudowany system logowania Apple, wprowadzony w iOS 10 i macOS 10.12. OSLog działa na poziomie jądra, strukturyzuje logi w formacie binarnym i zapewnia wbudowane filtrowanie przez Console.app. CocoaLumberjack — to biblioteka zewnętrzna, działająca na poziomie aplikacji.

Kiedy używać OSLog: do podstawowego logowania systemowego, gdy nie są potrzebne logi plikowe i niestandardowe formaty. OSLog — to właściwy wybór do logowania w skali systemu operacyjnego, gdzie ważna jest integracja z Console.app i Instruments.

Kiedy używać CocoaLumberjack: dla aplikacji produkcyjnych z potrzebą logów plikowych, rotacji, wielu kanałów zapisu, niestandardowych formatów i wydajności ponad 2 500 komunikatów na sekundę. CocoaLumberjack obsługuje również Swift Concurrency (async/await) od wersji 3.8.0.

Wiele aplikacji produkcyjnych łączy oba podejścia: OSLog do logowania systemowego (przez DDOSLogger jako jeden z loggerów) i DDFileLogger do logów produkcyjnych z rotacją i dostępem z urządzenia.