CocoaLumberjack: Temel kavramlar, mimari ve entegrasyon

CocoaLumberjack Nedir

CocoaLumberjack, 2010 yılında Robbie Hanson ve Deusty Designs tarafından oluşturulan Apple ekosistemi için açık kaynaklı bir loglama kütüphanesidir. Ana motivasyon, NSLog'un düşük performansıydı — terminale eşzamanlı yazma, az sayıda mesajda bile UI iş parçacığını yavaşlatıyordu.

Kütüphane çoklu logger mimarisi üzerine inşa edilmiştir: tek bir log mesajı birden fazla logger tarafından aynı anda işlenir. Her logger mesajı alır, kendi kurallarına göre biçimlendirir ve kendi kanalına (dosya, konsol, OSLog, uzak sunucu veya ağ) yazar. Tüm logger'lar arka plan kuyruğunda eşzamansız olarak çalışır ve UI iş parçacığını engellemez.

Deusty Designs Benchmarks, 2023'e göre, CocoaLumberjack bir dosyaya yazarken saniyede 10.200 log mesajı işlerken, NSLog aynı yük altında maksimum 1.200 mesaj sağlar. 8,5 katlık fark, eşzamansız mimari ve minimum kilitlemeden kaynaklanmaktadır.

Kütüphane iOS, macOS, tvOS, watchOS ve Swift Package Manager, CocoaPods ve Carthage'ı destekler. Mevcut kararlı sürüm, Swift 5.9+ ve Objective-C ARC ile uyumlu 3.8.5'tir (2024).

CocoaLumberjack Mimarisi: DDLog ve Logger'lar

CocoaLumberjack'in merkezi bileşeni, tüm loglama işlemleri için bir cephe görevi gören DDLog sınıfıdır. Geliştirici DDLog statik yöntemlerini çağırır ve cephe, mesajları kayıtlı logger'lara eşzamansız olarak dağıtır. Her logger, log(message:) yöntemiyle DDLogger protokolünü uygular ve biçimlendirilmiş hazır bir mesaj alır.

DDAbstractLogger — Temel Uygulama

DDAbstractLogger, özel logger'lar oluşturmak için temel işlevsellik sağlar: eşzamansız yazma için kuyruk, biçimlendirici ve filtreleme desteği. Geliştiricinin kendi logger'ını uygulamak için yalnızca log(message: DDLogMessage) yöntemini geçersiz kılması yeterlidir — örneğin, özel bir API'ye veya WebSocket'e log göndermek için.

Yerleşik Logger'lar

CocoaLumberjack dört yerleşik logger ile birlikte gelir: DDOSLogger — OSLog çıktısı (NSLog'un modern alternatifi), DDTTYLogger — renk vurgulamalı Xcode konsolu çıktısı (XcodeColors gerektirir), DDFileLogger — otomatik döndürmeli dosya yazma, DDASLLogger — Apple System Log çıktısı (iOS 15'ten beri kullanımdan kaldırıldı, DDOSLogger ile değiştirildi).

import CocoaLumberjack
import CocoaLumberjackSwift

// AppDelegate'de logger kurulumu
func configureLogging() {
    // OSLog — sistem loglaması için
    DDLog.add(DDOSLogger(sharedInstance))

    // Döndürmeli dosya logger'ı
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 saat
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Konsol — yalnızca hata ayıklama
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

Her logger için log seviyesi yapılandırması, veri akışının esnek bir şekilde kontrol edilmesini sağlar. Örneğin, DDFileLogger tüm seviyeleri (Debug ve üstü) kabul edebilirken, DDOSLogger yalnızca Warn ve Error'u kabul eder. Bu, her logger'ın logLevel özelliği aracılığıyla uygulanır.

iOS Projesinde Kurulum ve Yapılandırma

CocoaLumberjack'in kurulumu Swift Package Manager, CocoaPods veya Carthage aracılığıyla yapılır. Kurulumdan sonra, modülün içe aktarılması ve uygulama giriş noktasında (AppDelegate veya SwiftUI App) logger'ların yapılandırılması gerekir.

// Package.swift veya Xcode SPM aracılığıyla
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — minimum yapılandırma
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ı — CocoaLumberjack, DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose makrolarıyla ayrı bir CocoaLumberjackSwift modülü sağlar. Bu makrolar, her mesaja otomatik olarak dosya adı, satır numarası ve işlev adı ekleyerek bu verilerin manuel olarak belirtilmesi ihtiyacını ortadan kaldırır.

Önemli: Swift Package Manager kullanırken paketi tam sürümle eklediğinizden emin olun. En son kararlı sürüm 3.8.5, minimum iOS 12.0 veya macOS 10.13 gerektirir. iOS 11 ve altı projeler için 3.7.4 sürümünü kullanın.

DDFileLogger ve Log Dosyası Döndürme

DDFileLogger, CocoaLumberjack'in ana bileşenlerinden biridir ve otomatik döndürme ile dosya sistemine güvenilir log yazma sağlar. Üretim uygulamalarında, dosya loglama genellikle hata ayıklamada tekrarlanamayan sorunlar hakkında tek bilgi kaynağıdır.

Döndürme Parametreleri

rollingFrequency — yeni bir log dosyası oluşturma sıklığı (saniye cinsinden). 86400 (24 saat) değeri her gün yeni bir log dosyası oluşturur. maximumNumberOfLogFiles — diskteki maksimum dosya sayısı. logFileManager — dosya yaşam döngüsünü kontrol eden yönetici: oluşturma, arşivleme, eski dosyaları silme.

CocoaLumberjack Documentation, 2024'e göre, üretim için tipik yapılandırma: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (bir haftalık log), maximumFileSize = 10 MB (ek boyut sınırı). Bu yapılandırma diskte en fazla 70 MB yer kaplar ve tanı senaryolarının %99'unu kapsar.

Otomatik Sıkıştırma ve Arşivleme

doNotReuseLogFiles — mevcut dosyaların üzerine yazılmasını önleyen bir bayrak. true olarak ayarlandığında, her yeni dosya adında benzersiz bir zaman damgası alır. logFileManager, DDLogFileManagerDefault.compressLogFiles aracılığıyla eski dosyaların otomatik sıkıştırılmasını destekler — N günden eski dosyalar yerden tasarruf etmek için ZIP'e arşivlenir.

Cihazda Log Dosyalarına Erişim

DDFileLogger.logFileManager.sortedLogFilePaths, oluşturma tarihine göre sıralanmış tüm log dosyalarının yollarından oluşan bir dizi döndürür. Bu, uygulama içinde yerleşik bir log görüntüleyici uygulanmasına olanak tanır — Xcode'a erişimi olmayan beta test kullanıcıları ve kurumsal dağıtımlar için kullanışlıdır.

Biçimlendiriciler ve Filtreler: Çıktı Özelleştirme

Biçimlendiriciler (DDLogFormatter) — bir log mesajının logger'a iletilmeden önce nasıl bir dizeye dönüştürüleceğini tanımlayan bir protokoldür. Yerleşik biçimlendirici DDDispatchQueueLogFormatter, gönderme kuyruğunun adını ekler — bu, çoklu iş parçacıklı işlemlerin izlenmesini basitleştirir.

// Renk ve zamanla özel biçimlendirici
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)"
    }
}

// Biçimlendirici uygulaması
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filtreler (DDLogFilter) — logger düzeyinde mesajları filtrelemeye izin veren bir protokoldür. Yerleşik filtre DDLoggingContextSetFilter, yalnızca belirli bir bağlama sahip mesajları geçirir (örneğin, yalnızca ağ logları). Özel bir filtre, mesaj içeriğini, seviyesini, etiketini veya diğer özellikleri analiz edebilir.

Her logger'da biçimlendirici ve filtre kombinasyonu, kurumsal düzeyde esneklik sağlar. Örneğin, DDFileLogger ayrıntılı bir biçimlendirici (zaman damgası, seviye, dosya, işlev ile) ve “yalnızca Error” filtresi kullanabilirken, DDOSLogger kısa bir biçimlendirici ve “tüm seviyeler” filtresi kullanabilir.

CocoaLumberjack vs OSLog: Yaklaşım Karşılaştırması

OSLog, iOS 10 ve macOS 10.12'de tanıtılan Apple'ın yerleşik loglama sistemidir. OSLog çekirdek düzeyinde çalışır, logları ikili biçimde yapılandırır ve Console.app aracılığıyla yerleşik filtreleme sağlar. CocoaLumberjack, uygulama düzeyinde çalışan üçüncü taraf bir kütüphanedir.

OSLog ne zaman kullanılır: dosya logları ve özel biçimler gerekmediğinde temel sistem loglaması için. OSLog, Console.app ve Instruments ile entegrasyonun önemli olduğu işletim sistemi düzeyinde loglama için doğru seçimdir.

CocoaLumberjack ne zaman kullanılır: dosya logları, döndürme, birden çok çıktı kanalı, özel biçimlendiriciler ve saniyede 2.500 mesajı aşan performans gerektiren üretim uygulamaları için. CocoaLumberjack ayrıca 3.8.0 sürümünden itibaren Swift Concurrency'yi (async/await) destekler.

Birçok üretim uygulaması her iki yaklaşımı birleştirir: sistem loglaması için OSLog (logger'lardan biri olarak DDOSLogger aracılığıyla) ve döndürme ve cihaz erişimi ile üretim logları için DDFileLogger.