CocoaLumberjack: asosiy tushunchalar, arxitektura va integratsiya

CocoaLumberjack nima

CocoaLumberjack — Apple ekotizimi uchun ochiq manbali loglash kutubxonasi bo'lib, 2010-yilda Robbie Hanson va Deb Vermeer (Deusty Designs) tomonidan yaratilgan. Uni yaratishning asosiy sababi NSLog ning past ishlashi edi — terminalga sinxron yozish hatto kam sonli xabarlarda ham UI-ipini sekinlashtirardi.

Kutubxona multi-logger arxitekturasi asosida qurilgan: bitta log-xabar bir vaqtning o'zida bir nechta loggerlar tomonidan qayta ishlanadi. Har bir logger xabarni oladi, uni o'z qoidalariga muvofiq formatlaydi va o'z kanaliga — faylga, konsolga, OSLog ga, uzoq serverga yoki tarmoqqa yozadi. Barcha loggerlar fon navbatida asinxron ishlaydi, UI-ipini bloklamaydi.

Deusty Designs Benchmarks, 2023 ma'lumotlariga ko'ra, CocoaLumberjack faylga yozishda soniyada 10 200 log-xabarni qayta ishlaydi, NSLog esa xuddi shu yuklanishda maksimal 1 200 xabar beradi. 8.5 baravar farq asinxron arxitektura va bloklanishlarni minimallashtirish bilan bog'liq.

Kutubxona iOS, macOS, tvOS, watchOS va Swift Package Manager, CocoaPods va Carthage ni qo'llab-quvvatlaydi. Joriy barqaror versiya — 3.8.5 (2024), Swift 5.9+ va Objective-C ARC bilan mos keladi.

CocoaLumberjack arxitekturasi: DDLog va loggerlar

Markaziy komponent CocoaLumberjack — barcha loglash operatsiyalari uchun fasad vazifasini bajaradigan DDLog sinfidir. Dasturchi DDLog ning statik metodlarini chaqiradi, fasad esa xabarlarni ro'yxatdan o'tgan loggerlarga asinxron taqsimlaydi. Har bir logger tayyor formatlangan xabarni olib, DDLogger protokolini log(message:) metodi bilan amalga oshiradi.

DDAbstractLogger — asosiy implementatsiya

DDAbstractLogger maxsus loggerlar yaratish uchun asosiy funksionallikni taqdim etadi: asinxron yozish uchun navbat, formatter va filtrlashni qo'llab-quvvatlash. Dasturchiga o'z loggerini amalga oshirish uchun log(message: DDLogMessage) metodini override qilish yetarli — masalan, loglarni o'z API sini yoki WebSocket ni yuborish uchun.

O'rnatilgan loggerlar

CocoaLumberjack to'rtta o'rnatilgan logger bilan keladi: DDOSLogger — OSLog ga chiqish (NSLog ning zamonaviy muqobili), DDTTYLogger — rangli yoritish bilan Xcode konsoliga chiqish (XcodeColors ni talab qiladi), DDFileLogger — avtomatik aylanish bilan faylga yozish, DDASLLogger — Apple System Log ga chiqish (iOS 15 dan boshlab eskirgan, DDOSLogger bilan almashtirilgan).

import CocoaLumberjack
import CocoaLumberjackSwift

// AppDelegate da loggerlarni sozlash
func configureLogging() {
    // OSLog — tizim loglash uchun
    DDLog.add(DDOSLogger(sharedInstance))

    // Aylanishli fayl loggeri
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 soat
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konsol — faqat debug uchun
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Loglash darajasini sozlash har bir logger uchun ma'lumotlar oqimini moslashuvchan boshqarish imkonini beradi. Masalan, DDFileLogger barcha darajalarni (Debug va undan yuqori) qabul qilishi mumkin, DDOSLogger esa faqat Warn va Error ni. Bu har bir loggerning logLevel xususiyati orqali amalga oshiriladi.

iOS loyihasida o'rnatish va sozlash

O'rnatish CocoaLumberjack Swift Package Manager, CocoaPods yoki Carthage orqali amalga oshiriladi. O'rnatgandan so'ng modulni import qilish va loggerlarni ilovaning kirish nuqtasida — AppDelegate yoki SwiftUI App da sozlash kerak.

// Package.swift yoki Xcode SPM orqali
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimal konfiguratsiya
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 qobig'i — CocoaLumberjack DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose makroslari bilan alohida CocoaLumberjackSwift modulini taqdim etadi. Bu makroslar har bir xabarga avtomatik ravishda fayl nomini, qator raqamini va funksiya nomini qo'shadi, bu esa bu ma'lumotlarni qo'lda ko'rsatmasdan kuzatishni osonlashtiradi.

Muhim: Swift Package Manager dan foydalanganda paket aniq versiya bilan qo'shilganligiga ishonch hosil qiling. So'nggi barqaror versiya 3.8.5 minimal iOS 12.0 yoki macOS 10.13 versiyasini talab qiladi. iOS 11 va undan eski loyihalar uchun 3.7.4 versiyasidan foydalaning.

DDFileLogger va log-fayllar aylanishi

DDFileLogger — avtomatik aylanish bilan loglarni fayl tizimiga ishonchli yozishni ta'minlaydigan CocoaLumberjack ning asosiy komponentlaridan biridir. Ishlab chiqarish ilovalarida fayl loglash ko'pincha debug vaqtida takrorlanmaydigan muammolar haqidagi yagona ma'lumot manbai hisoblanadi.

Aylanish parametrlari

rollingFrequency — yangi fayl yaratish chastotasi (soniyalarda). 86400 (24 soat) qiymati har kuni yangi log-fayl yaratadi. maximumNumberOfLogFiles — diskdagi maksimal fayllar soni. logFileManager — fayllarning hayot sikli bilan boshqaradigan menejer: yaratish, arxivlash, eskilarni o'chirish.

CocoaLumberjack Documentation, 2024 ma'lumotlariga ko'ra, ishlab chiqarish uchun odatiy konfiguratsiya: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (bir haftalik loglar), maximumFileSize = 10 MB (hajm bo'yicha qo'shimcha cheklov). Bunday konfiguratsiya diskda 70 MB dan oshmaydi va diagnostika stsenariylarining 99% ini qamrab oladi.

Avtomatik siqish va arxivlash

doNotReuseLogFiles — mavjud fayllarni qayta yozishni taqiqlovchi bayroq. true qiymatida har bir yangi fayl nomda noyob timestamp oladi. logFileManager DDLogFileManagerDefault.compressLogFiles orqali eski fayllarni avtomatik siqishni qo'llab-quvvatlaydi — N kundan eski fayllar joyni tejash uchun ZIP ga arxivlanadi.

Qurilmadagi log-fayllarga kirish

DDFileLogger.logFileManager.sortedLogFilePaths yaratilgan sana bo'yicha tartiblangan barcha log-fayllar yo'llari massivini qaytaradi. Bu ilova ichida o'rnatilgan log ko'ruvchisini amalga oshirish imkonini beradi — Xcode ga kirish imkoni bo'lmagan beta-testchilar va enterprise joylashtirishlar uchun foydali.

Formatterlar va filtrlar: chiqishni sozlash

Formatterlar (DDLogFormatter) — log-xabar logger ga yuborilishidan oldin qanday qilib satrga aylantirilishini belgilaydigan protokol. O'rnatilgan DDDispatchQueueLogFormatter formatteri dispatch navbati nomini qo'shadi — bu ko'p tarmoqli operatsiyalarni kuzatishni osonlashtiradi.

// Rang va vaqt bilan maxsus 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)"
    }
}

// Formatterning qo'llanilishi
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtrlar (DDLogFilter) — xabarlarni logger darajasida saralash imkonini beruvchi protokol. O'rnatilgan DDLoggingContextSetFilter filtri faqat ma'lum kontekstli xabarlarni (masalan, faqat tarmoq loglarini) o'tkazadi. Maxsus filtr xabar mazmunini, darajasini, tag ini yoki boshqa atributlarni tahlil qilishi mumkin.

Har bir loggerda formatter va filtr kombinatsiyasi korporativ darajadagi moslashuvchanlikni beradi. Masalan, DDFileLogger batafsil formatter (timestamp, daraja, fayl, funksiya bilan) va „faqat Error" filtri, DDOSLogger esa qisqa formatter va „barcha darajalar" filtri ishlatishi mumkin.

CocoaLumberjack OSLog ga qarshi: yondashuvlarni taqqoslash

OSLog — iOS 10 va macOS 10.12 da taqdim etilgan Apple ning o'rnatilgan loglash tizimi. OSLog yadro darajasida ishlaydi, loglarni ikkilik formatda tuziladi va Console.app orqali o'rnatilgan filtrlashni ta'minlaydi. CocoaLumberjack — ilova darajasida ishlaydigan uchinchi tomon kutubxonasi.

OSLog ni qachon ishlatish kerak: fayl loglari va maxsus formatlar kerak bo'lmagan asosiy tizim loglash uchun. OSLog — Console.app va Instruments bilan integratsiya muhim bo'lgan OS miqyosida loglash uchun to'g'ri tanlovdir.

CocoaLumberjack ni qachon ishlatish kerak: fayl loglariga, aylanishga, ko'p chiqish kanallariga, maxsus formatterlarga va soniyada 2 500 xabardan yuqori ishlashga ehtiyoji bo'lgan ishlab chiqarish ilovalari uchun. CocoaLumberjack 3.8.0 versiyasidan boshlab Swift Concurrency (async/await) ni ham qo'llab-quvvatlaydi.

Ko'plab ishlab chiqarish ilovalari ikkala yondashuvni birlashtiradi: tizim loglash uchun OSLog (loggerlardan biri sifatida DDOSLogger orqali) va aylanish bilan qurilmadan kirish uchun DDFileLogger.