CocoaLumberjack: المفاهيم الأساسية والهندسة والتكامل

ما هو CocoaLumberjack

CocoaLumberjack هي مكتبة تسجيل مفتوحة المصدر للنظام البيئي Apple أنشأها Robbie Hanson و Deusty Designs في عام 2010. كان الدافع الرئيسي هو الأداء المنخفض لـ NSLog — حيث كانت الكتابة المتزامنة إلى الطرفية تبطئ مؤشر واجهة المستخدم حتى مع عدد صغير من الرسائل.

المكتبة مبنية على بنية متعددة المسجلات: تتم معالجة رسالة تسجيل واحدة بواسطة عدة مسجلات في وقت واحد. يستقبل كل مسجل الرسالة، ويقوم بتنسيقها وفقًا لقواعده الخاصة، ويكتبها في قناته الخاصة — ملف، وحدة تحكم، OSLog، خادم بعيد، أو شبكة. تعمل جميع المسجلات بشكل غير متزامن في قائمة انتظار خلفية، دون حظر مؤشر واجهة المستخدم.

وفقًا لـ معايير Deusty Designs، 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 والمسجلات

المكون المركزي لـ CocoaLumberjack هو فئة DDLog، التي تعمل كواجهة لجميع عمليات التسجيل. يقوم المطور باستدعاء الطرق الثابتة لـ DDLog، وتقوم الواجهة بتوزيع الرسائل بشكل غير متزامن على المسجلات المسجلة. يقوم كل مسجل بتطبيق بروتوكول DDLogger بطريقة log(message:)، ويتلقى رسالة منسقة جاهزة.

DDAbstractLogger — التنفيذ الأساسي

DDAbstractLogger يوفر وظائف أساسية لإنشاء مسجلات مخصصة: قائمة انتظار للكتابة غير المتزامنة، منسق، ودعم التصفية. يحتاج المطور فقط إلى تجاوز طريقة log(message: DDLogMessage) لتنفيذ المسجل الخاص به — على سبيل المثال، لإرسال السجلات إلى API مخصصة أو WebSocket.

المسجلات المضمنة

يأتي CocoaLumberjack مع أربعة مسجلات مضمنة: DDOSLogger — الإخراج إلى OSLog (بديل حديث لـ NSLog)، DDTTYLogger — الإخراج إلى وحدة تحكم Xcode مع تمييز بالألوان (يتطلب XcodeColors)، DDFileLogger — الكتابة إلى ملف مع التدوير التلقائي، DDASLLogger — الإخراج إلى Apple System Log (مهمل منذ iOS 15، تم استبداله بـ DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// إعداد المسجلات في AppDelegate
func configureLogging() {
    // OSLog — للتسجيل النظامي
    DDLog.add(DDOSLogger(sharedInstance))

    // مسجل الملفات مع التدوير
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 ساعة
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // وحدة التحكم — للتصحيح فقط
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

تكوين مستوى التسجيل لكل مسجل يسمح بالتحكم المرن في تدفق البيانات. على سبيل المثال، يمكن لـ DDFileLogger قبول جميع المستويات (Debug وما فوق)، بينما يقبل DDOSLogger فقط Warn و Error. يتم ذلك من خلال خاصية logLevel لكل مسجل.

التثبيت والإعداد في مشروع iOS

يتم تثبيت CocoaLumberjack عبر Swift Package Manager أو CocoaPods أو Carthage. بعد التثبيت، تحتاج إلى استيراد الوحدة وتكوين المسجلات في نقطة دخول التطبيق — 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، حيث يوفر كتابة موثوقة للسجلات في نظام الملفات مع التدوير التلقائي. في تطبيقات الإنتاج، غالبًا ما يكون تسجيل الملفات هو المصدر الوحيد للمعلومات حول المشكلات التي لا يمكن إعادة إنتاجها في التصحيح.

معلمات التدوير

rollingFrequency — تكرار إنشاء ملف سجل جديد (بالثواني). القيمة 86400 (24 ساعة) تنشئ ملف سجل جديد كل يوم. maximumNumberOfLogFiles — الحد الأقصى لعدد الملفات على القرص. logFileManager — المدير الذي يتحكم في دورة حياة الملفات: الإنشاء، الأرشفة، حذف الملفات القديمة.

وفقًا لوثائق CocoaLumberjack، 2024، التكوين النموذجي للإنتاج: rollingFrequency = 86400، maximumNumberOfLogFiles = 7 (أسبوع من السجلات)، maximumFileSize = 10 MB (حد إضافي للحجم). يشغل هذا التكوين ما لا يزيد عن 70 MB على القرص ويغطي 99% من سيناريوهات التشخيص.

الضغط والأرشفة التلقائيان

doNotReuseLogFiles — علامة تمنع الكتابة فوق الملفات الموجودة. عند التعيين على true، يتلقى كل ملف جديد طابعًا زمنيًا فريدًا في اسمه. يدعم logFileManager الضغط التلقائي للملفات القديمة عبر DDLogFileManagerDefault.compressLogFiles — يتم أرشفة الملفات الأقدم من N يومًا في ZIP لتوفير المساحة.

الوصول إلى ملفات السجل على الجهاز

DDFileLogger.logFileManager.sortedLogFilePaths يُرجع مصفوفة من المسارات لجميع ملفات السجل مرتبة حسب تاريخ الإنشاء. يسمح ذلك بتنفيذ عارض سجل مدمج داخل التطبيق — مفيد للمختبرين التجريبيين والنشر للمؤسسات حيث لا يوجد وصول إلى Xcode.

المنسقون والمرشحات: تخصيص المخرجات

المنسقون (DDLogFormatter) — بروتوكول يحدد كيفية تحويل رسالة السجل إلى سلسلة قبل تمريرها إلى المسجل. يضيف المنسق المضمن DDDispatchQueueLogFormatter اسم قائمة انتظار الإرسال — وهذا يبسط تتبع العمليات متعددة الخيوط.

// منسق مخصص مع اللون والوقت
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) — بروتوكول يسمح بتصفية الرسائل على مستوى المسجل. يمرر المرشح المضمن DDLoggingContextSetFilter الرسائل ذات السياق المحدد فقط (على سبيل المثال، سجلات الشبكة فقط). يمكن للمرشح المخصص تحليل محتوى الرسالة أو مستواها أو علامتها أو أي سمات أخرى.

مزيج المنسق والمرشح على كل مسجل يوفر مرونة على مستوى المؤسسات. على سبيل المثال، يمكن لـ DDFileLogger استخدام منسق مفصل (مع طابع زمني ومستوى وملف ووظيفة) ومرشح «خطأ فقط»، بينما يستخدم DDOSLogger منسقًا موجزًا ومرشح «جميع المستويات».

CocoaLumberjack مقابل OSLog: مقارنة النهج

OSLog هو نظام التسجيل المضمن من Apple الذي تم تقديمه في iOS 10 و macOS 10.12. يعمل OSLog على مستوى kernel، وينظم السجلات في تنسيق ثنائي، ويوفر تصفية مضمنة عبر Console.app. CocoaLumberjack هي مكتبة تابعة لجهة خارجية تعمل على مستوى التطبيق.

متى تستخدم OSLog: للتسجيل الأساسي للنظام عندما لا تكون هناك حاجة لسجلات الملفات والتنسيقات المخصصة. OSLog هو الخيار الصحيح للتسجيل على مستوى نظام التشغيل حيث يكون التكامل مع Console.app و Instruments مهمًا.

متى تستخدم CocoaLumberjack: لتطبيقات الإنتاج التي تحتاج إلى سجلات ملفات وتدوير وقنوات إخراج متعددة ومنسقين مخصصين وأداء يتجاوز 2,500 رسالة في الثانية. يدعم CocoaLumberjack أيضًا Swift Concurrency (async/await) بدءًا من الإصدار 3.8.0.

تجمع العديد من تطبيقات الإنتاج بين كلا النهجين: OSLog للتسجيل النظامي (عبر DDOSLogger كأحد المسجلات) و DDFileLogger لسجلات الإنتاج مع التدوير والوصول من الجهاز.