CocoaLumberjack: mga pangunahing konsepto, arkitektura, at integrasyon

Ano ang CocoaLumberjack

CocoaLumberjack — ay isang open-source na library ng logging para sa ecosystem ng Apple, na nilikha nina Robbie Hanson at Deb Vermeer (Deusty Designs) noong 2010. Ang pangunahing motibasyon ay ang mababang performance ng NSLog — ang synchronous na pagsusulat sa terminal ay nagpapabagal sa thread ng UI kahit na sa maliit na bilang ng mga mensahe.

Ang library ay binuo sa arkitektura ng multi-logger: isang log na mensahe ang pinoproseso nang sabay-sabay ng ilang logger. Bawat logger ay tumatanggap ng mensahe, ini-format ito ayon sa sariling mga patakaran, at isinusulat ito sa sariling channel — file, console, OSLog, remote na server, o network. Lahat ng logger ay gumagana nang asynchronous sa background na queue, nang hindi hinaharangan ang thread ng UI.

Ayon sa datos ng Deusty Designs Benchmarks, 2023, pinoproseso ng CocoaLumberjack ang 10 200 na log na mensahe bawat segundo kapag nagsusulat sa file, samantalang ang NSLog ay naghahatid ng maximum na 1 200 na mensahe sa parehong karga. Ang pagkakaibang 8.5 beses ay dahil sa asynchronous na arkitektura at pagliit ng mga pagharang.

Sinusuportahan ng library ang iOS, macOS, tvOS, watchOS at ang Swift Package Manager, CocoaPods, at Carthage. Ang kasalukuyang stable na bersyon — 3.8.5 (2024), katugma sa Swift 5.9+ at Objective-C ARC.

Arkitektura ng CocoaLumberjack: DDLog at mga logger

Ang sentral na komponente ng CocoaLumberjack — ang klase DDLog, na gumaganap bilang façade para sa lahat ng operasyon ng logging. Tinatawag ng developer ang mga static na method ng DDLog, at ipinamahagi ng façade nang asynchronous ang mga mensahe sa mga nakarehistrong logger. Bawat logger ay nag-iimplementa ng protokol na DDLogger gamit ang method na log(message:), na tumatanggap ng handa nang na-format na mensahe.

DDAbstractLogger — pangunahing implementasyon

DDAbstractLogger ay nagbibigay ng pangunahing functionality para sa paglikha ng mga custom na logger: queue para sa asynchronous na pagsusulat, formatter, at suporta para sa pag-filter. Sapat na para sa developer ang i-override ang method na log(message: DDLogMessage) para mag-implementa ng sariling logger — halimbawa, para magpadala ng mga log sa sariling API o WebSocket.

Mga built-in na logger

Ang CocoaLumberjack ay may kasamang apat na built-in na logger: DDOSLogger — output sa OSLog (modernong alternatibo sa NSLog), DDTTYLogger — output sa Xcode console na may kulay na pag-highlight (nangangailangan ng XcodeColors), DDFileLogger — pagsusulat sa file na may awtomatikong rotation, DDASLLogger — output sa Apple System Log (deprecated mula sa iOS 15, pinalitan ng DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Pag-configure ng mga logger sa AppDelegate
func configureLogging() {
    // OSLog — para sa sistema ng logging
    DDLog.add(DDOSLogger(sharedInstance))

    // File logger na may rotation
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 na oras
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Console — para lang sa debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Ang pagtatakda ng level ng logging para sa bawat logger ay nagpapahintulot ng flexible na kontrol sa daloy ng data. Halimbawa, ang DDFileLogger ay maaaring tumanggap ng lahat ng level (Debug at mas mataas), samantalang ang DDOSLogger — Warn at Error lang. Ito ay ipinapatupad sa pamamagitan ng property na logLevel ng bawat logger.

Pag-install at pag-configure sa proyektong iOS

Ang pag-install ng CocoaLumberjack ay ginagawa sa pamamagitan ng Swift Package Manager, CocoaPods, o Carthage. Pagkatapos ng pag-install, kailangang i-import ang module at i-configure ang mga logger sa entry point ng app — AppDelegate o SwiftUI App.

// Package.swift o sa pamamagitan ng Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimum na configuration
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 — nagbibigay ang CocoaLumberjack ng hiwalay na module na CocoaLumberjackSwift na may mga macro na DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Awtomatikong idinadagdag ng mga macro na ito ang pangalan ng file, numero ng linya, at pangalan ng function sa bawat mensahe, na nagpapadali sa pag-trace nang hindi manu-manong tinutukoy ang mga datos na ito.

Mahalaga: kapag gumagamit ng Swift Package Manager, tiyakin na ang package ay idinagdag na may eksaktong bersyon. Ang pinakabagong stable na bersyon na 3.8.5 ay nangangailangan ng minimum na bersyong iOS 12.0 o macOS 10.13. Para sa mga proyektong may iOS 11 at mas luma, gamitin ang bersyong 3.7.4.

DDFileLogger at rotation ng mga log file

DDFileLogger — isa sa mga pangunahing komponente ng CocoaLumberjack, na tinitiyak ang maaasahang pagsusulat ng mga log sa file system na may awtomatikong rotation. Sa mga production app, ang file logging ay madalas na tanging pinagmumulan ng impormasyon tungkol sa mga problema na hindi nagagawa muli sa debugging.

Mga parameter ng rotation

rollingFrequency — dalas ng paggawa ng bagong file (sa mga segundo). Ang halagang 86400 (24 oras) ay gumagawa ng bagong log file araw-araw. maximumNumberOfLogFiles — maximum na bilang ng mga file sa disk. logFileManager — tagapamahala na kumokontrol sa lifecycle ng mga file: paggawa, pag-archive, pagtanggal ng mga luma.

Ayon sa datos ng CocoaLumberjack Documentation, 2024, ang tipikal na configuration para sa production: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (isang linggong log), maximumFileSize = 10 MB (karagdagang limitasyon ayon sa laki). Ang ganitong configuration ay tumatagal ng hindi hihigit sa 70 MB sa disk at sumasakop sa 99% ng mga diagnostic na senaryo.

Awtomatikong compression at pag-archive

doNotReuseLogFiles — isang flag na nagbabawal sa pag-overwrite ng mga umiiral na file. Sa halagang true, bawat bagong file ay tumatanggap ng natatanging timestamp sa pangalan. logFileManager ay sumusuporta sa awtomatikong compression ng mga lumang file sa pamamagitan ng DDLogFileManagerDefault.compressLogFiles — ang mga file na mas luma sa N araw ay naka-archive sa ZIP para makatipid ng espasyo.

Access sa mga log file sa device

DDFileLogger.logFileManager.sortedLogFilePaths ay nagbabalik ng array ng mga path sa lahat ng log file, na pinag-uuri ayon sa petsa ng paggawa. Ito ay nagpapahintulot ng pag-implementa ng built-in na viewer ng mga log sa loob ng app — kapaki-pakinabang para sa mga beta tester at enterprise deployment kung saan walang access sa Xcode.

Mga formatter at filter: pag-customize ng output

Mga formatter (DDLogFormatter) — isang protokol na tumutukoy kung paano binabago ang log na mensahe sa isang string bago ipasa sa logger. Ang built-in na formatter na DDDispatchQueueLogFormatter ay nagdaragdag ng pangalan ng dispatch queue — pinapadali nito ang pag-trace ng mga multithreaded na operasyon.

// Custom na formatter na may kulay at oras
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)"
    }
}

// Paglalapat ng formatter
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Mga filter (DDLogFilter) — isang protokol na nagpapahintulot ng pagtanggal ng mga mensahe sa antas ng logger. Ang built-in na filter na DDLoggingContextSetFilter ay nagpapadaan lamang ng mga mensahe na may partikular na konteksto (halimbawa, mga network log lamang). Ang custom na filter ay maaaring mag-analisa ng nilalaman ng mensahe, level, tag, o anumang iba pang katangian.

Ang kumbinasyon ng formatter at filter sa bawat logger ay nagbibigay ng flexibility sa antas ng enterprise. Halimbawa, ang DDFileLogger ay maaaring gumamit ng detalyadong formatter (may timestamp, level, file, function) at filter na "Error lamang", samantalang ang DDOSLogger — maikling formatter at filter na "lahat ng level".

CocoaLumberjack vs OSLog: paghahambing ng mga diskarte

OSLog — ang built-in na sistema ng logging ng Apple, na ipinakilala sa iOS 10 at macOS 10.12. Gumagana ang OSLog sa antas ng kernel, ini-istruktura ang mga log sa binary na format, at nagbibigay ng built-in na pag-filter sa pamamagitan ng Console.app. Ang CocoaLumberjack — ay third-party na library na gumagana sa antas ng app.

Kailan gagamitin ang OSLog: para sa pangunahing sistema ng logging, kapag hindi kailangan ang mga log file at custom na format. Ang OSLog ay tamang pagpili para sa logging sa sukat ng OS, kung saan mahalaga ang integrasyon sa Console.app at Instruments.

Kailan gagamitin ang CocoaLumberjack: para sa mga production app na may pangangailangan sa mga log file, rotation, maraming output channel, custom na formatter, at performance na higit sa 2 500 na mensahe bawat segundo. Sinusuportahan din ng CocoaLumberjack ang Swift Concurrency (async/await) mula sa bersyong 3.8.0.

Maraming production app ang pinagsasama ang parehong diskarte: OSLog para sa sistema ng logging (sa pamamagitan ng DDOSLogger bilang isa sa mga logger) at DDFileLogger para sa mga production log na may rotation at access mula sa device.