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 console с цветной подсветкой (требует 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 для продакшен-логов с ротацией и доступом с устройства.