CocoaLumberjack: əsas anlayışlar, arxitektura və inteqrasiya

CocoaLumberjack nədir

CocoaLumberjack — 2010-cu ildə Robbie Hanson və Deb Vermeer (Deusty Designs) tərəfindən yaradılmış Apple ekosistemi üçün open-source loglama kitabxanasıdır. Yaradılmasının əsas motivasiyası NSLog-un aşağı performansı idi — terminala sinxron yazma hətta az sayda mesajda belə UI-axını yavaşladırdı.

Kitabxana multi-logger arxitekturası üzərində qurulub: bir loq mesajı eyni anda bir neçə logger tərəfindən emal olunur. Hər logger mesajı alır, öz qaydalarına uyğun formatlayır və öz kanalına — fayla, konsola, OSLog-a, uzaq serverə və ya şəbəkəyə yazır. Bütün loggerlər arxa fonda asinxron işləyir, UI-axınını bloklamır.

Deusty Designs Benchmarks, 2023 məlumatlarına görə, CocoaLumberjack fayla yazarkən saniyədə 10 200 loq mesajı emal edir, NSLog isə eyni yükdə maksimum 1 200 mesaj verir. 8.5 dəfə fərq asinxron arxitektura və bloklamaların minimallaşdırılması ilə əldə olunur.

Kitabxana iOS, macOS, tvOS, watchOS və Swift Package Manager, CocoaPods və Carthage-i dəstəkləyir. Cari stabil versiya — 3.8.5 (2024), Swift 5.9+ və Objective-C ARC ilə uyğundur.

CocoaLumberjack arxitekturası: DDLog və loggerlər

Mərkəzi komponent CocoaLumberjack — bütün loglama əməliyyatları üçün fasad rolunu oynayan DDLog sinfidir. Tərtibatçı DDLog-un statik metodlarını çağırır, fasad isə mesajları qeydiyyatdan keçmiş loggerlərə asinxron paylayır. Hər logger hazır formatlanmış mesajı alaraq DDLogger protokolunu log(message:) metodu ilə tətbiq edir.

DDAbstractLogger — əsas tətbiq

DDAbstractLogger xüsusi loggerlər yaratmaq üçün əsas funksionallıq təqdim edir: asinxron yazma üçün növbə, formatçı və filtrasiya dəstəyi. Tərtibatçıya öz loggerini tətbiq etmək üçün log(message: DDLogMessage) metodunu override etmək kifayətdir — məsələn, loqları öz API-yə və ya WebSocket-ə göndərmək üçün.

Quraşdırılmış loggerlər

CocoaLumberjack dörd quraşdırılmış loggerlə gəlir: DDOSLogger — OSLog-a çıxış (NSLog-un müasir alternativi), DDTTYLogger — rəngli işıqlandırma ilə Xcode konsoluna çıxış (XcodeColors tələb edir), DDFileLogger — avtomatik rotasiya ilə fayla yazma, DDASLLogger — Apple System Log-a çıxış (iOS 15-dən etibarən deprecated, DDOSLogger ilə əvəz olunub).

import CocoaLumberjack
import CocoaLumberjackSwift

// AppDelegate-də loggerlərin konfiqurasiyası
func configureLogging() {
    // OSLog — sistem loglaması üçün
    DDLog.add(DDOSLogger(sharedInstance))

    // Rotasiyalı fayl loggeri
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 saat
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konsol — yalnız debug üçün
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Loglama səviyyəsinin təyini hər logger üçün məlumat axınını çevik idarə etməyə imkan verir. Məsələn, DDFileLogger bütün səviyyələri (Debug və yuxarı) qəbul edə bilər, DDOSLogger isə yalnız Warn və Error. Bu, hər loggerin logLevel xassəsi vasitəsilə həyata keçirilir.

iOS layihəsində quraşdırma və konfiqurasiya

Quraşdırma CocoaLumberjack Swift Package Manager, CocoaPods və ya Carthage vasitəsilə həyata keçirilir. Quraşdırmadan sonra modulu import etmək və loggerləri tətbiqin giriş nöqtəsində — AppDelegate və ya SwiftUI App-də konfiqurasiya etmək lazımdır.

// Package.swift və ya Xcode SPM vasitəsilə
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimal konfiqurasiya
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 sarmalayıcısı — CocoaLumberjack DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose makroları ilə ayrıca CocoaLumberjackSwift modulunu təqdim edir. Bu makrolar hər mesaja avtomatik olaraq fayl adını, sətir nömrəsini və funksiya adını əlavə edir ki, bu da bu məlumatları əl ilə göstərmədən izləməyi asanlaşdırır.

Vacib: Swift Package Manager istifadə edərkən paketin dəqiq versiya ilə əlavə edildiyinə əmin olun. Son stabil versiya 3.8.5 minimum iOS 12.0 və ya macOS 10.13 tələb edir. iOS 11 və daha köhnə layihələr üçün 3.7.4 versiyasından istifadə edin.

DDFileLogger və loq-faylların rotasiyası

DDFileLogger — avtomatik rotasiya ilə loqların fayl sisteminə etibarlı yazılmasını təmin edən CocoaLumberjack-in əsas komponentlərindən biridir. Production tətbiqlərində fayl loglaması çox vaxt debug zamanı bərpa olunmayan problemlər haqqında yeganə məlumat mənbəyidir.

Rotasiya parametrləri

rollingFrequency — yeni faylın yaradılma tezliyi (saniyələrlə). 86400 (24 saat) dəyəri hər gün yeni loq-fayl yaradır. maximumNumberOfLogFiles — diskdəki maksimum fayl sayı. logFileManager — faylların həyat dövrünü idarə edən menecer: yaradılma, arxivləşdirmə, köhnələrin silinməsi.

CocoaLumberjack Documentation, 2024 məlumatlarına görə, production üçün tipik konfiqurasiya: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (bir həftəlik loqlar), maximumFileSize = 10 MB (ölçüyə görə əlavə məhdudiyyət). Bu konfiqurasiya diskdə 70 MB-dan çox yer tutmur və diaqnostika ssenarilərinin 99%-ni əhatə edir.

Avtomatik sıxılma və arxivləşdirmə

doNotReuseLogFiles — mövcud faylların üzərinə yazılmasını qadağan edən bayraq. true dəyərində hər yeni fayl adda unikal timestamp alır. logFileManager DDLogFileManagerDefault.compressLogFiles vasitəsilə köhnə faylların avtomatik sıxılmasını dəstəkləyir — N gündən köhnə fayllar yerə qənaət üçün ZIP-ə arxivlənir.

Cihazda loq-fayllara giriş

DDFileLogger.logFileManager.sortedLogFilePaths yaradılma tarixinə görə sıralanmış bütün loq-faylların yolları massivini qaytarır. Bu, tətbiqin içində quraşdırılmış loq baxıcısını tətbiq etməyə imkan verir — Xcode-a girişi olmayan beta-testçilər və enterprise yerləşdirmələri üçün faydalıdır.

Formatçılar və filtrlər: çıxışın fərdiləşdirilməsi

Formatçılar (DDLogFormatter) — loq mesajının loggerə ötürülməzdən əvvəl sətirə necə çevrildiyini müəyyən edən protokol. Quraşdırılmış DDDispatchQueueLogFormatter formatçısı dispetçer növbəsinin adını əlavə edir — bu, çoxtread əməliyyatlarının izlənməsini asanlaşdırır.

// Rəng və vaxt ilə xüsusi formatçı
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)"
    }
}

// Formatçının tətbiqi
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtrlər (DDLogFilter) — mesajları logger səviyyəsində kənarlaşdırmağa imkan verən protokol. Quraşdırılmış DDLoggingContextSetFilter filtri yalnız müəyyən kontekstli mesajları (məsələn, yalnız network-loqlarını) buraxır. Xüsusi filtr mesajın məzmununu, səviyyəsini, tag-ni və ya digər atributları təhlil edə bilər.

Hər loggerdə formatçı və filtrin kombinasiyası enterprise səviyyəli çeviklik verir. Məsələn, DDFileLogger ətraflı formatçı (timestamp, səviyyə, fayl, funksiya ilə) və „yalnız Error" filtri, DDOSLogger isə qısa formatçı və „bütün səviyyələr" filtri istifadə edə bilər.

CocoaLumberjack vs OSLog: yanaşmaların müqayisəsi

OSLog — iOS 10 və macOS 10.12-də təqdim edilmiş Apple-ın quraşdırılmış loglama sistemidir. OSLog kernel səviyyəsində işləyir, loqları binar formatda strukturlaşdırır və Console.app vasitəsilə quraşdırılmış filtrasiya təmin edir. CocoaLumberjack isə tətbiq səviyyəsində işləyən üçüncü tərəf kitabxanasıdır.

OSLog nə vaxt istifadə edilməlidir: fayl loqları və xüsusi formatlar lazım olmayan əsas sistem loglaması üçün. OSLog — Console.app və Instruments ilə inteqrasiyanın vacib olduğu OS miqyaslı loglama üçün düzgün seçimdir.

CocoaLumberjack nə vaxt istifadə edilməlidir: fayl loqlarına, rotasiyaya, çoxsaylı çıxış kanallarına, xüsusi formatçılara və saniyədə 2 500 mesajdan yuxarı performansa ehtiyacı olan production tətbiqləri üçün. CocoaLumberjack həmçinin 3.8.0 versiyasından etibarən Swift Concurrency (async/await) dəstəkləyir.

Bir çox production tətbiqi hər iki yanaşmanı birləşdirir: sistem loglaması üçün OSLog (loggerlərdən biri kimi DDOSLogger vasitəsilə) və rotasiya ilə cihazdan giriş üçün DDFileLogger.