CocoaLumberjack: ключови понятия, архитектура и интеграция

Какво е CocoaLumberjack

CocoaLumberjack — е библиотека с отворен код за регистриране в екосистемата на Apple, създадена от Роби Хансън (Robbie Hanson) и Деб Вермер (Deusty Designs) през 2010 г. Основният мотив за създаването ѝ беше ниската производителност на NSLog — синхронният запис в терминала забавяше UI-нишката дори при малък брой съобщения.

Библиотеката е изградена на архитектурата multi-logger: едно лог-съобщение се обработва едновременно от няколко логъра. Всеки логър получава съобщението, форматира го по свои правила и го записва в своя канал — файл, конзола, 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, който играе ролята на фасада за всички операции по регистриране. Разработчикът извиква статичните методи на DDLog, а фасадата асинхронно разпределя съобщенията към регистрираните логъри. Всеки логър реализира протокола DDLogger с метод log(message:), получавайки готовото форматирано съобщение.

DDAbstractLogger — основна реализация

DDAbstractLogger предоставя основната функционалност за създаване на персонализирани логъри: опашка за асинхронен запис, форматиращ модул и поддръжка на филтриране. Достатъчно е разработчикът да преопредели метода log(message: DDLogMessage), за да реализира собствен логър — например, за изпращане на логове към собствено API или WebSocket.

Вградени логъри

CocoaLumberjack се доставя с четири вградени логъра: DDOSLogger — изход към OSLog (съвременна алтернатива на NSLog), DDTTYLogger — изход към конзолата на Xcode с цветно подчертаване (изисква XcodeColors), DDFileLogger — запис във файл с автоматична ротация, DDASLLogger — изход към Apple System Log (deprecated от 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)

    // Конзола — само за debug
    #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 Documentation, 2024, типичната конфигурация за производствена среда: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (седмица логове), maximumFileSize = 10 MB (допълнително ограничение по размер). Такава конфигурация заема на диска не повече от 70 MB и покрива 99% от сценариите за диагностика.

Автоматично компресиране и архивиране

doNotReuseLogFiles — флаг, който забранява презаписването на съществуващи файлове. При стойност true всеки нов файл получава уникален timestamp в името. logFileManager поддържа автоматично компресиране на стари файлове чрез DDLogFileManagerDefault.compressLogFiles — файлове, по-стари от N дни, се архивират в ZIP за пестене на място.

Достъп до лог-файловете на устройството

DDFileLogger.logFileManager.sortedLogFilePaths връща масив от пътища до всички лог-файлове, сортирани по дата на създаване. Това позволява реализирането на вграден преглеждач на логове в приложението — полезно за бета тестери и enterprise внедрявания, където няма достъп до 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 пропуска само съобщения с определен контекст (например само мрежови логове). Персонализиран филтър може да анализира съдържанието на съобщението, нивото, tag-а или всякакви други атрибути.

Комбинацията от форматиращ модул и филтър на всеки логър дава гъвкавост на корпоративно ниво. Например DDFileLogger може да използва подробен форматиращ модул (с timestamp, ниво, файл, функция) и филтър „само Error”, а DDOSLogger — кратък форматиращ модул и филтър „всички нива”.

CocoaLumberjack срещу OSLog: сравнение на подходите

OSLog — вградената система за регистриране на Apple, представена в iOS 10 и macOS 10.12. OSLog работи на ниво ядро, структурира логовете в двоичен формат и предоставя вградено филтриране чрез Console.app. CocoaLumberjack — библиотека на трета страна, която работи на ниво приложение.

Кога да използвате OSLog: за основно системно регистриране, когато не са нужни файлови логове и персонализирани формати. OSLog е правилният избор за регистриране в мащаба на ОС, където е важна интеграцията с Console.app и Instruments.

Кога да използвате CocoaLumberjack: за производствени приложения с нужда от файлови логове, ротация, множество изходни канали, персонализирани форматиращи модули и производителност над 2 500 съобщения в секунда. CocoaLumberjack също така поддържа Swift Concurrency (async/await) от версия 3.8.0.

Много производствени приложения комбинират двата подхода: OSLog за системно регистриране (чрез DDOSLogger като един от логърите) и DDFileLogger за производствени логове с ротация и достъп от устройството.