CocoaLumberjack: مفاهیم کلیدی، معماری و یکپارچه‌سازی

CocoaLumberjack چیست

CocoaLumberjack — یک کتابخانه متن‌باز ثبت لاگ برای اکوسیستم اپل است که توسط رابی هانسون (Robbie Hanson) و دب ورمیر (Deusty Designs) در سال ۲۰۱۰ ایجاد شده است. انگیزه اصلی ایجاد آن کارایی پایین NSLog بود — نوشتن همزمان در ترمینال حتی با تعداد کمی پیام، رشته UI را کند می‌کرد.

این کتابخانه بر معماری multi-logger ساخته شده است: یک پیام لاگ به‌طور همزمان توسط چندین logger پردازش می‌شود. هر logger پیام را دریافت می‌کند، آن را طبق قوانین خودش قالب‌بندی می‌کند و در کانال خود — فایل، کنسول، OSLog، سرور راه دور یا شبکه — می‌نویسد. همه loggerها به‌صورت ناهمزمان در صف پس‌زمینه کار می‌کنند و رشته UI را مسدود نمی‌کنند.

طبق داده‌های Deusty Designs Benchmarks, 2023، CocoaLumberjack هنگام نوشتن در فایل ۱۰٬۲۰۰ پیام لاگ در ثانیه را پردازش می‌کند، در حالی که NSLog با همان بار حداکثر ۱٬۲۰۰ پیام ارائه می‌دهد. تفاوت ۸.۵ برابری به معماری ناهمزمان و به حداقل رساندن مسدودسازی‌ها مربوط می‌شود.

این کتابخانه از iOS، macOS، tvOS، watchOS و Swift Package Manager، CocoaPods و Carthage پشتیبانی می‌کند. نسخه پایدار فعلی — 3.8.5 (۲۰۲۴)، سازگار با Swift 5.9+ و Objective-C ARC است.

معماری CocoaLumberjack: DDLog و loggerها

مؤلفه مرکزی CocoaLumberjack — کلاس DDLog است که به‌عنوان نمای تمام عملیات ثبت لاگ عمل می‌کند. توسعه‌دهنده متدهای استاتیک DDLog را فراخوانی می‌کند و نمای آن پیام‌ها را به‌صورت ناهمزمان بین loggerهای ثبت‌شده توزیع می‌کند. هر logger پروتکل DDLogger را با متد log(message:) پیاده‌سازی می‌کند و پیام قالب‌بندی‌شده آماده را دریافت می‌کند.

DDAbstractLogger — پیاده‌سازی پایه

DDAbstractLogger عملکرد پایه برای ایجاد loggerهای سفارشی فراهم می‌کند: صف برای نوشتن ناهمزمان، قالب‌ساز و پشتیبانی از فیلتر کردن. برای توسعه‌دهنده کافی است متد log(message: DDLogMessage) را برای پیاده‌سازی logger خودش override کند — مثلاً برای ارسال لاگ‌ها به API خودش یا WebSocket.

loggerهای داخلی

CocoaLumberjack با چهار logger داخلی عرضه می‌شود: DDOSLogger — خروجی به OSLog (جایگزین مدرن NSLog)، DDTTYLogger — خروجی به کنسول Xcode با هایلایت رنگی (نیازمند XcodeColors)، DDFileLogger — نوشتن در فایل با چرخش خودکار، DDASLLogger — خروجی به Apple System Log (منسوخ از iOS 15، جایگزین شده با DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// پیکربندی loggerها در AppDelegate
func configureLogging() {
    // OSLog — برای ثبت لاگ سیستم
    DDLog.add(DDOSLogger(sharedInstance))

    // logger فایلی با چرخش
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // ۲۴ ساعت
    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 انجام می‌شود. پس از نصب باید ماژول را import کنید و loggerها را در نقطه ورود برنامه — 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 — 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 است که نوشتن قابل اعتماد لاگ‌ها در سیستم فایل را با چرخش خودکار تضمین می‌کند. در برنامه‌های production، ثبت لاگ در فایل اغلب تنها منبع اطلاعات درباره مشکلاتی است که در اشکال‌زدایی بازتولید نمی‌شوند.

پارامترهای چرخش

rollingFrequency — بسامد ایجاد فایل جدید (به ثانیه). مقدار ۸۶۴۰۰ (۲۴ ساعت) هر روز یک فایل لاگ جدید ایجاد می‌کند. maximumNumberOfLogFiles — حداکثر تعداد فایل‌ها روی دیسک. logFileManager — مدیر کنترل چرخه حیات فایل‌ها: ایجاد، بایگانی، حذف فایل‌های قدیمی.

طبق داده‌های CocoaLumberjack Documentation, 2024، پیکربندی معمول برای production: rollingFrequency = 86400، maximumNumberOfLogFiles = 7 (یک هفته لاگ)، maximumFileSize = 10 MB (محدودیت اضافی بر اساس اندازه). چنین پیکربندی حداکثر ۷۰ مگابایت روی دیسک اشغال می‌کند و ۹۹٪ سناریوهای تشخیص خطا را پوشش می‌دهد.

فشرده‌سازی و بایگانی خودکار

doNotReuseLogFiles — پرچمی که بازنویسی فایل‌های موجود را ممنوع می‌کند. با مقدار true هر فایل جدید یک timestamp یکتا در نام می‌گیرد. logFileManager فشرده‌سازی خودکار فایل‌های قدیمی را از طریق DDLogFileManagerDefault.compressLogFiles پشتیبانی می‌کند — فایل‌های قدیمی‌تر از N روز برای صرفه‌جویی در فضا در ZIP بایگانی می‌شوند.

دسترسی به فایل‌های لاگ روی دستگاه

DDFileLogger.logFileManager.sortedLogFilePaths آرایه‌ای از مسیرهای همه فایل‌های لاگ را که بر اساس تاریخ ایجاد مرتب شده‌اند برمی‌گرداند. این امکان نمایش‌دهنده داخلی لاگ‌ها را داخل برنامه فراهم می‌کند — مفید برای تست‌کننده‌های بتا و استقرارهای سازمانی که به Xcode دسترسی ندارند.

قالب‌سازها و فیلترها: شخصی‌سازی خروجی

قالب‌سازها (DDLogFormatter) — پروتکلی که تعیین می‌کند پیام لاگ قبل از ارسال به logger چگونه به رشته تبدیل شود. قالب‌ساز داخلی DDDispatchQueueLogFormatter نام صف dispatch را اضافه می‌کند — این کار ردیابی عملیات چندنخی را ساده می‌کند.

// قالب‌ساز سفارشی با رنگ و زمان
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)"
    }
}

// اعمال قالب‌ساز
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

فیلترها (DDLogFilter) — پروتکلی که امکان حذف پیام‌ها را در سطح logger فراهم می‌کند. فیلتر داخلی DDLoggingContextSetFilter فقط پیام‌هایی با زمینه مشخص را عبور می‌دهد (مثلاً فقط لاگ‌های شبکه). یک فیلتر سفارشی می‌تواند محتوای پیام، سطح، برچسب یا هر ویژگی دیگری را تحلیل کند.

ترکیب قالب‌ساز و فیلتر روی هر logger انعطاف‌پذیری سطح سازمانی می‌دهد. مثلاً DDFileLogger می‌تواند از قالب‌ساز تفصیلی (با timestamp، سطح، فایل، تابع) و فیلتر «فقط Error» استفاده کند، در حالی که DDOSLogger از قالب‌ساز مختصر و فیلتر «همه سطوح».

CocoaLumberjack در برابر OSLog: مقایسه رویکردها

OSLog — سیستم ثبت لاگ داخلی اپل است که در iOS 10 و macOS 10.12 معرفی شده. OSLog در سطح هسته کار می‌کند، لاگ‌ها را در قالب باینری ساختاربندی می‌کند و فیلتر داخلی از طریق Console.app فراهم می‌کند. CocoaLumberjack — کتابخانه شخص ثالثی است که در سطح برنامه کار می‌کند.

چه زمانی OSLog را استفاده کنیم: برای ثبت لاگ پایه سیستم، زمانی که به فایل‌های لاگ و قالب‌های سفارشی نیاز نیست. OSLog انتخاب درستی برای ثبت لاگ در مقیاس سیستم‌عامل است که در آن یکپارچگی با Console.app و Instruments مهم است.

چه زمانی CocoaLumberjack را استفاده کنیم: برای برنامه‌های production با نیاز به فایل‌های لاگ، چرخش، کانال‌های خروجی متعدد، قالب‌سازهای سفارشی و کارایی بیش از ۲٬۵۰۰ پیام در ثانیه. CocoaLumberjack همچنین از Swift Concurrency (async/await) از نسخه 3.8.0 پشتیبانی می‌کند.

بسیاری از برنامه‌های production هر دو رویکرد را ترکیب می‌کنند: OSLog برای ثبت لاگ سیستم (از طریق DDOSLogger به‌عنوان یکی از loggerها) و DDFileLogger برای لاگ‌های production با چرخش و دسترسی از دستگاه.