CocoaLumberjack: konsep kunci, arsitektur, dan integrasi

Apa itu CocoaLumberjack

CocoaLumberjack — adalah pustaka logging open-source untuk ekosistem Apple, dibuat oleh Robbie Hanson dan Deb Vermeer (Deusty Designs) pada tahun 2010. Motivasi utama pembuatannya adalah performa rendah NSLog — penulisan sinkron ke terminal memperlambat thread UI bahkan dengan jumlah pesan yang sedikit.

Pustaka ini dibangun di atas arsitektur multi-logger: satu pesan log diproses secara bersamaan oleh beberapa logger. Setiap logger menerima pesan, memformatnya sesuai aturannya sendiri, dan menulisnya ke kanalnya — file, konsol, OSLog, server jarak jauh, atau jaringan. Semua logger bekerja secara asinkron di antrean latar belakang, tanpa memblokir thread UI.

Menurut data Deusty Designs Benchmarks, 2023, CocoaLumberjack memproses 10 200 pesan log per detik saat menulis ke file, sedangkan NSLog menghasilkan maksimal 1 200 pesan pada beban yang sama. Perbedaan 8.5 kali disebabkan oleh arsitektur asinkron dan minimalisasi pemblokiran.

Pustaka ini mendukung iOS, macOS, tvOS, watchOS serta Swift Package Manager, CocoaPods, dan Carthage. Versi stabil saat ini — 3.8.5 (2024), kompatibel dengan Swift 5.9+ dan Objective-C ARC.

Arsitektur CocoaLumberjack: DDLog dan logger

Komponen pusat CocoaLumberjack — kelas DDLog, yang bertindak sebagai fasad untuk semua operasi logging. Pengembang memanggil metode statis DDLog, dan fasad tersebut secara asinkron mendistribusikan pesan ke logger yang terdaftar. Setiap logger mengimplementasikan protokol DDLogger dengan metode log(message:), menerima pesan terformat yang sudah jadi.

DDAbstractLogger — implementasi dasar

DDAbstractLogger menyediakan fungsionalitas dasar untuk membuat logger kustom: antrean untuk penulisan asinkron, formatter, dan dukungan pemfilteran. Pengembang cukup menimpa metode log(message: DDLogMessage) untuk mengimplementasikan logger sendiri — misalnya, untuk mengirim log ke API sendiri atau WebSocket.

Logger bawaan

CocoaLumberjack hadir dengan empat logger bawaan: DDOSLogger — keluaran ke OSLog (alternatif modern untuk NSLog), DDTTYLogger — keluaran ke konsol Xcode dengan sorotan warna (membutuhkan XcodeColors), DDFileLogger — penulisan ke file dengan rotasi otomatis, DDASLLogger — keluaran ke Apple System Log (deprecated sejak iOS 15, digantikan oleh DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Konfigurasi logger di AppDelegate
func configureLogging() {
    // OSLog — untuk logging sistem
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger file dengan rotasi
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 jam
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

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

Pengaturan level logging untuk setiap logger memungkinkan kontrol fleksibel atas aliran data. Misalnya, DDFileLogger dapat menerima semua level (Debug dan di atasnya), sedangkan DDOSLogger — hanya Warn dan Error. Ini diimplementasikan melalui properti logLevel setiap logger.

Instalasi dan konfigurasi di proyek iOS

Instalasi CocoaLumberjack dilakukan melalui Swift Package Manager, CocoaPods, atau Carthage. Setelah instalasi, Anda perlu mengimpor modul dan mengonfigurasi logger di titik masuk aplikasi — AppDelegate atau SwiftUI App.

// Package.swift atau melalui Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — konfigurasi minimal
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
    }
}

Wrapper Swift — CocoaLumberjack menyediakan modul terpisah CocoaLumberjackSwift dengan makro DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Makro-makro ini secara otomatis menambahkan nama file, nomor baris, dan nama fungsi ke setiap pesan, yang menyederhanakan pelacakan tanpa menentukan data ini secara manual.

Penting: saat menggunakan Swift Package Manager, pastikan paket ditambahkan dengan versi yang tepat. Versi stabil terbaru 3.8.5 membutuhkan versi minimum iOS 12.0 atau macOS 10.13. Untuk proyek dengan iOS 11 dan lebih lama, gunakan versi 3.7.4.

DDFileLogger dan rotasi file log

DDFileLogger — salah satu komponen kunci CocoaLumberjack, yang memastikan penulisan log yang andal ke sistem file dengan rotasi otomatis. Di aplikasi production, logging file sering menjadi satu-satunya sumber informasi tentang masalah yang tidak dapat direproduksi saat debugging.

Parameter rotasi

rollingFrequency — frekuensi pembuatan file baru (dalam detik). Nilai 86400 (24 jam) membuat file log baru setiap hari. maximumNumberOfLogFiles — jumlah maksimum file di disk. logFileManager — pengelola yang mengatur siklus hidup file: pembuatan, pengarsipan, penghapusan yang lama.

Menurut data CocoaLumberjack Documentation, 2024, konfigurasi khas untuk production: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (seminggu log), maximumFileSize = 10 MB (batasan tambahan berdasarkan ukuran). Konfigurasi seperti ini memakan tidak lebih dari 70 MB di disk dan mencakup 99% skenario diagnostik.

Kompresi dan pengarsipan otomatis

doNotReuseLogFiles — bendera yang melarang penimpaan file yang ada. Pada nilai true, setiap file baru menerima timestamp unik di namanya. logFileManager mendukung kompresi otomatis file lama melalui DDLogFileManagerDefault.compressLogFiles — file yang lebih lama dari N hari diarsipkan ke ZIP untuk menghemat ruang.

Akses ke file log di perangkat

DDFileLogger.logFileManager.sortedLogFilePaths mengembalikan array path ke semua file log, yang diurutkan berdasarkan tanggal pembuatan. Ini memungkinkan penerapan penampil log bawaan di dalam aplikasi — berguna untuk penguji beta dan deployment enterprise di mana tidak ada akses ke Xcode.

Formatter dan filter: kustomisasi keluaran

Formatter (DDLogFormatter) — protokol yang menentukan bagaimana pesan log diubah menjadi string sebelum diteruskan ke logger. Formatter bawaan DDDispatchQueueLogFormatter menambahkan nama antrean dispatch — ini menyederhanakan pelacakan operasi multi-thread.

// Formatter kustom dengan warna dan waktu
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)"
    }
}

// Penerapan formatter
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Filter (DDLogFilter) — protokol yang memungkinkan penyaringan pesan di tingkat logger. Filter bawaan DDLoggingContextSetFilter hanya meloloskan pesan dengan konteks tertentu (misalnya, hanya log jaringan). Filter kustom dapat menganalisis isi pesan, level, tag, atau atribut lainnya.

Kombinasi formatter dan filter pada setiap logger memberikan fleksibilitas tingkat enterprise. Misalnya, DDFileLogger dapat menggunakan formatter terperinci (dengan timestamp, level, file, fungsi) dan filter "hanya Error", sedangkan DDOSLogger — formatter ringkas dan filter "semua level".

CocoaLumberjack vs OSLog: perbandingan pendekatan

OSLog — sistem logging bawaan Apple, diperkenalkan di iOS 10 dan macOS 10.12. OSLog bekerja di tingkat kernel, menstrukturkan log dalam format biner, dan menyediakan pemfilteran bawaan melalui Console.app. CocoaLumberjack — pustaka pihak ketiga yang bekerja di tingkat aplikasi.

Kapan menggunakan OSLog: untuk logging sistem dasar, ketika log file dan format kustom tidak diperlukan. OSLog adalah pilihan yang tepat untuk logging dalam skala OS, di mana integrasi dengan Console.app dan Instruments penting.

Kapan menggunakan CocoaLumberjack: untuk aplikasi production dengan kebutuhan log file, rotasi, beberapa kanal keluaran, formatter kustom, dan performa lebih dari 2 500 pesan per detik. CocoaLumberjack juga mendukung Swift Concurrency (async/await) mulai dari versi 3.8.0.

Banyak aplikasi production menggabungkan kedua pendekatan: OSLog untuk logging sistem (melalui DDOSLogger sebagai salah satu logger) dan DDFileLogger untuk log production dengan rotasi dan akses dari perangkat.