CocoaLumberjack: کلیدی تصورات، فن تعمیر اور انضمام

CocoaLumberjack کیا ہے

CocoaLumberjack Apple ماحولیاتی نظام کے لیے ایک اوپن سورس لاگنگ لائبریری ہے جسے 2010 میں Robbie Hanson اور Deusty Designs نے بنایا تھا۔ بنیادی محرک NSLog کی کم کارکردگی تھی — ٹرمینل پر ہم وقت ساز رائٹنگ پیغامات کی کم تعداد کے باوجود UI تھریڈ کو سست کر دیتی تھی۔

لائبریری ملٹی لاگر فن تعمیر پر بنائی گئی ہے: ایک ہی لاگ پیغام کو متعدد لاگرز بیک وقت پروسیس کرتے ہیں۔ ہر لاگر پیغام وصول کرتا ہے، اسے اپنے قوانین کے مطابق فارمیٹ کرتا ہے، اور اسے اپنے چینل — فائل، کنسول، OSLog، ریموٹ سرور یا نیٹ ورک — پر لکھتا ہے۔ تمام لاگرز بیک گراؤنڈ قطار میں غیر ہم وقت ساز طور پر کام کرتے ہیں، UI تھریڈ کو بلاک کیے بغیر۔

Deusty Designs Benchmarks، 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 کلاس ہے، جو تمام لاگنگ آپریشنز کے لیے facade کے طور پر کام کرتی ہے۔ ڈیویلپر DDLog کے جامد طریقوں کو کال کرتا ہے، اور facade رجسٹرڈ لاگرز کو غیر ہم وقت ساز طور پر پیغامات تقسیم کرتا ہے۔ ہر لاگر log(message:) طریقہ کے ساتھ DDLogger پروٹوکول کو لاگو کرتا ہے، ایک تیار فارمیٹ شدہ پیغام وصول کرتا ہے۔

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 DDLogDebug، DDLogInfo، DDLogWarn، DDLogError، DDLogVerbose میکروز کے ساتھ ایک علیحدہ CocoaLumberjackSwift ماڈیول فراہم کرتا ہے۔ یہ میکروز خود بخود ہر پیغام میں فائل کا نام، لائن نمبر اور فنکشن کا نام شامل کرتے ہیں، دستی طور پر ڈیٹا کی وضاحت کیے بغیر ٹریسنگ کو آسان بناتے ہیں۔

اہم: 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 Documentation، 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 ایک تفصیلی فارمیٹر (ٹائم اسٹیمپ، سطح، فائل، فنکشن کے ساتھ) اور “صرف Error” فلٹر استعمال کر سکتا ہے، جبکہ DDOSLogger ایک مختصر فارمیٹر اور “تمام سطحیں” فلٹر استعمال کرتا ہے۔

CocoaLumberjack بمقابلہ OSLog: طریقوں کا موازنہ

OSLog Apple کا بلٹ ان لاگنگ سسٹم ہے جو iOS 10 اور macOS 10.12 میں متعارف کرایا گیا تھا۔ OSLog کرنل سطح پر کام کرتا ہے، لاگز کو بائنری فارمیٹ میں تشکیل دیتا ہے، اور Console.app کے ذریعے بلٹ ان فلٹرنگ فراہم کرتا ہے۔ CocoaLumberjack ایک تھرڈ پارٹی لائبریری ہے جو ایپلیکیشن سطح پر کام کرتی ہے۔

OSLog کب استعمال کریں: بنیادی سسٹم لاگنگ کے لیے جب فائل لاگز اور کسٹم فارمیٹس کی ضرورت نہ ہو۔ OSLog OS سطح کی لاگنگ کے لیے صحیح انتخاب ہے جہاں Console.app اور Instruments کے ساتھ انضمام اہم ہے۔

CocoaLumberjack کب استعمال کریں: پروڈکشن ایپلیکیشنز کے لیے جنہیں فائل لاگز، گردش، متعدد آؤٹ پٹ چینلز، کسٹم فارمیٹرز اور 2,500 پیغامات فی سیکنڈ سے زیادہ کارکردگی کی ضرورت ہوتی ہے۔ CocoaLumberjack ورژن 3.8.0 سے Swift Concurrency (async/await) کو بھی سپورٹ کرتا ہے۔

بہت سی پروڈکشن ایپلیکیشنز دونوں طریقوں کو یکجا کرتی ہیں: سسٹم لاگنگ کے لیے OSLog (ایک لاگر کے طور پر DDOSLogger کے ذریعے) اور گردش اور ڈیوائس تک رسائی کے ساتھ پروڈکشن لاگز کے لیے DDFileLogger۔