CocoaLumberjack: βασικές έννοιες, αρχιτεκτονική και ενσωμάτωση

Τι είναι το CocoaLumberjack

CocoaLumberjack — είναι μια ανοιχτού κώδικα βιβλιοθήκη καταγραφής για το οικοσύστημα της Apple, που δημιουργήθηκε από τους Robbie Hanson και Deb Vermeer (Deusty Designs) το 2010. Το κύριο κίνητρο δημιουργίας ήταν η χαμηλή απόδοση του NSLog — η σύγχρονη εγγραφή στο τερματικό επιβράδυνε το νήμα UI ακόμη και με μικρό αριθμό μηνυμάτων.

Η βιβλιοθήκη βασίζεται στην αρχιτεκτονική multi-logger: ένα μήνυμα καταγραφής επεξεργάζεται ταυτόχρονα από πολλούς loggers. Κάθε logger λαμβάνει το μήνυμα, το μορφοποιεί σύμφωνα με τους δικούς του κανόνες και το γράφει στο δικό του κανάλι — αρχείο, κονσόλα, OSLog, απομακρυσμένο διακομιστή ή δίκτυο. Όλοι οι loggers λειτουργούν ασύγχρονα σε ουρά παρασκηνίου, χωρίς να μπλοκάρουν το νήμα 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 και loggers

Το κεντρικό στοιχείο του CocoaLumberjack — η κλάση DDLog, που λειτουργεί ως πρόσοψη για όλες τις λειτουργίες καταγραφής. Ο προγραμματιστής καλεί τις στατικές μεθόδους του DDLog, και η πρόσοψη κατανέμει ασύγχρονα τα μηνύματα στους καταχωρημένους loggers. Κάθε logger υλοποιεί το πρωτόκολλο DDLogger με τη μέθοδο log(message:), λαμβάνοντας το έτοιμο μορφοποιημένο μήνυμα.

DDAbstractLogger — βασική υλοποίηση

DDAbstractLogger παρέχει βασική λειτουργικότητα για τη δημιουργία προσαρμοσμένων loggers: ουρά για ασύγχρονη εγγραφή, formatter και υποστήριξη φιλτραρίσματος. Αρκεί ο προγραμματιστής να παρακάμψει τη μέθοδο log(message: DDLogMessage) για να υλοποιήσει τον δικό του logger — για παράδειγμα, για την αποστολή καταγραφών στο δικό του API ή WebSocket.

Ενσωματωμένοι loggers

Το CocoaLumberjack διατίθεται με τέσσερις ενσωματωμένους loggers: DDOSLogger — έξοδος στο OSLog (σύγχρονη εναλλακτική του NSLog), DDTTYLogger — έξοδος στην κονσόλα του Xcode με έγχρωμη επισήμανση (απαιτεί XcodeColors), DDFileLogger — εγγραφή σε αρχείο με αυτόματη περιστροφή, DDASLLogger — έξοδος στο Apple System Log (καταργημένο από το iOS 15, αντικαταστάθηκε από το DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Ρύθμιση loggers στο AppDelegate
func configureLogging() {
    // OSLog — για καταγραφή συστήματος
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger αρχείου με περιστροφή
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 ώρες
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Κονσόλα — μόνο για debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Η ρύθμιση του επιπέδου καταγραφής για κάθε logger επιτρέπει ευέλικτο έλεγχο της ροής δεδομένων. Για παράδειγμα, το DDFileLogger μπορεί να δέχεται όλα τα επίπεδα (Debug και άνω), ενώ το DDOSLogger — μόνο Warn και Error. Αυτό υλοποιείται μέσω της ιδιότητας logLevel κάθε logger.

Εγκατάσταση και ρύθμιση σε έργο iOS

Η εγκατάσταση του CocoaLumberjack γίνεται μέσω Swift Package Manager, CocoaPods ή Carthage. Μετά την εγκατάσταση, πρέπει να εισαχθεί η ενότητα και να ρυθμιστούν οι loggers στο σημείο εισόδου της εφαρμογής — 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 wrapper — το 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 επιστρέφει έναν πίνακα διαδρομών προς όλα τα αρχεία καταγραφής, ταξινομημένα κατά ημερομηνία δημιουργίας. Αυτό επιτρέπει την υλοποίηση ενσωματωμένου προγράμματος προβολής καταγραφών μέσα στην εφαρμογή — χρήσιμο για beta testers και αναπτύξεις enterprise, όπου δεν υπάρχει πρόσβαση στο Xcode.

Formatter και φίλτρα: προσαρμογή της εξόδου

Formatter (DDLogFormatter) — ένα πρωτόκολλο που καθορίζει πώς μετατρέπεται το μήνυμα καταγραφής σε συμβολοσειρά πριν από τη μεταφορά στον logger. Ο ενσωματωμένος formatter DDDispatchQueueLogFormatter προσθέτει το όνομα της ουράς dispatch — αυτό απλοποιεί την ανίχνευση λειτουργιών πολλαπλών νημάτων.

// Προσαρμοσμένος formatter με χρώμα και χρόνο
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)"
    }
}

// Εφαρμογή formatter
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Φίλτρα (DDLogFilter) — ένα πρωτόκολλο που επιτρέπει την απόρριψη μηνυμάτων σε επίπεδο logger. Το ενσωματωμένο φίλτρο DDLoggingContextSetFilter επιτρέπει να περάσουν μόνο μηνύματα με συγκεκριμένο πλαίσιο (για παράδειγμα, μόνο καταγραφές δικτύου). Ένα προσαρμοσμένο φίλτρο μπορεί να αναλύει το περιεχόμενο του μηνύματος, το επίπεδο, το tag ή οποιαδήποτε άλλα χαρακτηριστικά.

Ο συνδυασμός formatter και φίλτρου σε κάθε logger δίνει ευελιξία επιπέδου enterprise. Για παράδειγμα, το DDFileLogger μπορεί να χρησιμοποιεί λεπτομερή formatter (με timestamp, επίπεδο, αρχείο, συνάρτηση) και φίλτρο "μόνο Error", ενώ το DDOSLogger — σύντομο formatter και φίλτρο "όλα τα επίπεδα".

CocoaLumberjack έναντι OSLog: σύγκριση προσεγγίσεων

OSLog — το ενσωματωμένο σύστημα καταγραφής της Apple, που εισήχθη στο iOS 10 και το macOS 10.12. Το OSLog λειτουργεί σε επίπεδο πυρήνα, δομεί τις καταγραφές σε δυαδική μορφή και παρέχει ενσωματωμένο φιλτράρισμα μέσω του Console.app. Το CocoaLumberjack — είναι βιβλιοθήκη τρίτου μέρους που λειτουργεί σε επίπεδο εφαρμογής.

Πότε να χρησιμοποιείτε το OSLog: για βασική καταγραφή συστήματος, όταν δεν χρειάζονται αρχεία καταγραφής και προσαρμοσμένες μορφές. Το OSLog είναι η σωστή επιλογή για καταγραφή σε κλίμακα λειτουργικού συστήματος, όπου είναι σημαντική η ενσωμάτωση με το Console.app και το Instruments.

Πότε να χρησιμοποιείτε το CocoaLumberjack: για εφαρμογές παραγωγής με ανάγκη για αρχεία καταγραφής, περιστροφή, πολλαπλά κανάλια εξόδου, προσαρμοσμένους formatter και απόδοση άνω των 2 500 μηνυμάτων ανά δευτερόλεπτο. Το CocoaLumberjack υποστηρίζει επίσης το Swift Concurrency (async/await) από την έκδοση 3.8.0.

Πολλές εφαρμογές παραγωγής συνδυάζουν και τις δύο προσεγγίσεις: OSLog για καταγραφή συστήματος (μέσω του DDOSLogger ως ενός από τους loggers) και DDFileLogger για καταγραφές παραγωγής με περιστροφή και πρόσβαση από τη συσκευή.