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

Що таке CocoaLumberjack

CocoaLumberjack — це open-source бібліотека логування для екосистеми 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, що забезпечує надійний запис логів у файлову систему з автоматичною ротацією. У production-додатках файлове логування часто є єдиним джерелом інформації про проблеми, які не відтворюються під час налагодження.

Параметри ротації

rollingFrequency — частота створення нового файлу (в секундах). Значення 86400 (24 години) створює новий лог-файл щодня. maximumNumberOfLogFiles — максимальна кількість файлів на диску. logFileManager — менеджер, який керує життєвим циклом файлів: створення, архівація, видалення старих.

За даними CocoaLumberjack Documentation, 2024, типова конфігурація для production: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (тиждень логів), maximumFileSize = 10 MB (додаткове обмеження за розміром). Така конфігурація займає на диску не більше 70 MB та покриває 99% сценаріїв діагностики.

Автоматичне стиснення та архівація

doNotReuseLogFiles — прапорець, що забороняє перезапис існуючих файлів. При значенні true кожен новий файл отримує унікальний timestamp в імені. logFileManager підтримує автоматичне стиснення старих файлів через DDLogFileManagerDefault.compressLogFiles — файли старші за N днів архівуються в ZIP для економії місця.

Доступ до лог-файлів на пристрої

DDFileLogger.logFileManager.sortedLogFilePaths повертає масив шляхів до всіх лог-файлів, відсортованих за датою створення. Це дозволяє реалізувати вбудований viewer логів всередині додатка — корисно для beta-тестерів та 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 пропускає лише повідомлення з певним контекстом (наприклад, тільки network-логи). Кастомний фільтр може аналізувати вміст повідомлення, рівень, tag або будь-які інші атрибути.

Комбінація форматувальника та фільтра на кожному логері дає гнучкість enterprise-рівня. Наприклад, DDFileLogger може використовувати детальний форматувальник (з timestamp, рівнем, файлом, функцією) та фільтр "тільки Error", а DDOSLogger — короткий форматувальник та фільтр "всі рівні".

CocoaLumberjack vs OSLog: порівняння підходів

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

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

Коли використовувати CocoaLumberjack: для production-додатків із потребою у файлових логах, ротації, множинних каналах виведення, кастомних форматувальниках та продуктивності понад 2 500 повідомлень на секунду. CocoaLumberjack також підтримує Swift Concurrency (async/await) починаючи з версії 3.8.0.

Багато production-додатків комбінують обидва підходи: OSLog для системного логування (через DDOSLogger як один із логерів) та DDFileLogger для продакшн-логів із ротацією та доступом із пристрою.