CocoaLumberjack: Conceitos-chave, arquitetura e integração

O que é CocoaLumberjack

CocoaLumberjack é uma biblioteca de logging de código aberto para o ecossistema Apple criada por Robbie Hanson e Deusty Designs em 2010. A principal motivação foi o baixo desempenho do NSLog — a gravação síncrona no terminal diminuía a thread da UI mesmo com um pequeno número de mensagens.

A biblioteca é construída sobre uma arquitetura multi-logger: uma única mensagem de log é processada por vários loggers simultaneamente. Cada logger recebe a mensagem, formata-a de acordo com suas próprias regras e a escreve em seu próprio canal — arquivo, console, OSLog, servidor remoto ou rede. Todos os loggers trabalham assincronamente em uma fila em segundo plano, sem bloquear a thread da UI.

De acordo com Deusty Designs Benchmarks, 2023, o CocoaLumberjack processa 10.200 mensagens de log por segundo ao escrever em um arquivo, enquanto o NSLog entrega no máximo 1.200 mensagens sob a mesma carga. A diferença de 8,5 vezes é devida à arquitetura assíncrona e à minimização de bloqueios.

A biblioteca suporta iOS, macOS, tvOS, watchOS e Swift Package Manager, CocoaPods e Carthage. A versão estável atual é 3.8.5 (2024), compatível com Swift 5.9+ e Objective-C ARC.

Arquitetura do CocoaLumberjack: DDLog e Loggers

O componente central do CocoaLumberjack é a classe DDLog, que atua como fachada para todas as operações de logging. O desenvolvedor chama métodos estáticos do DDLog, e a fachada distribui assincronamente as mensagens para os loggers registrados. Cada logger implementa o protocolo DDLogger com o método log(message:), recebendo uma mensagem formatada pronta.

DDAbstractLogger — Implementação base

DDAbstractLogger fornece funcionalidade básica para criar loggers personalizados: uma fila para gravação assíncrona, um formatador e suporte a filtragem. O desenvolvedor só precisa sobrescrever o método log(message: DDLogMessage) para implementar seu próprio logger — por exemplo, para enviar logs para uma API personalizada ou WebSocket.

Loggers incorporados

CocoaLumberjack vem com quatro loggers incorporados: DDOSLogger — saída para OSLog (alternativa moderna ao NSLog), DDTTYLogger — saída para o console do Xcode com destaque de cor (requer XcodeColors), DDFileLogger — gravação em arquivo com rotação automática, DDASLLogger — saída para o Apple System Log (obsoleto desde o iOS 15, substituído pelo DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Configuração de loggers no AppDelegate
func configureLogging() {
    // OSLog — para logging do sistema
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger de arquivo com rotação
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 horas
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

    // Console — apenas debug
    #if DEBUG
    DDLog.add(DDTTYLogger(sharedInstance))
    #endif
}

A configuração do nível de log para cada logger permite controle flexível do fluxo de dados. Por exemplo, o DDFileLogger pode aceitar todos os níveis (Debug e acima), enquanto o DDOSLogger apenas Warn e Error. Isso é implementado através da propriedade logLevel de cada logger.

Instalação e configuração em projeto iOS

A instalação do CocoaLumberjack é feita via Swift Package Manager, CocoaPods ou Carthage. Após a instalação, é necessário importar o módulo e configurar os loggers no ponto de entrada do aplicativo — AppDelegate ou SwiftUI App.

// Package.swift ou via Xcode SPM
// https://github.com/CocoaLumberjack/CocoaLumberjack.git

// AppDelegate.swift — configuração mínima
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
    }
}

O wrapper Swift — CocoaLumberjack fornece um módulo separado CocoaLumberjackSwift com macros DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Essas macros adicionam automaticamente o nome do arquivo, número da linha e nome da função a cada mensagem, simplificando o rastreio sem especificar manualmente esses dados.

Importante: ao usar o Swift Package Manager, certifique-se de adicionar o pacote com a versão exata. A versão estável mais recente 3.8.5 requer iOS 12.0 ou macOS 10.13 como mínimo. Para projetos com iOS 11 e inferior, use a versão 3.7.4.

DDFileLogger e rotação de arquivos de log

DDFileLogger é um dos principais componentes do CocoaLumberjack, fornecendo gravação confiável de logs no sistema de arquivos com rotação automática. Em aplicativos de produção, o logging em arquivo é frequentemente a única fonte de informação sobre problemas que não podem ser reproduzidos em depuração.

Parâmetros de rotação

rollingFrequency — a frequência de criação de um novo arquivo de log (em segundos). Um valor de 86400 (24 horas) cria um novo arquivo de log a cada dia. maximumNumberOfLogFiles — o número máximo de arquivos no disco. logFileManager — o gerenciador que controla o ciclo de vida dos arquivos: criação, arquivamento, exclusão de arquivos antigos.

De acordo com a Documentação do CocoaLumberjack, 2024, uma configuração típica para produção: rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (uma semana de logs), maximumFileSize = 10 MB (limite adicional de tamanho). Esta configuração ocupa não mais que 70 MB em disco e cobre 99% dos cenários de diagnóstico.

Compressão e arquivamento automáticos

doNotReuseLogFiles — uma flag que impede a sobrescrita de arquivos existentes. Quando definido como true, cada novo arquivo recebe um timestamp único em seu nome. logFileManager suporta compressão automática de arquivos antigos via DDLogFileManagerDefault.compressLogFiles — arquivos com mais de N dias são arquivados em ZIP para economizar espaço.

Acesso aos arquivos de log no dispositivo

DDFileLogger.logFileManager.sortedLogFilePaths retorna um array de caminhos para todos os arquivos de log ordenados por data de criação. Isso permite implementar um visualizador de logs integrado dentro do aplicativo — útil para testadores beta e implantações empresariais onde não há acesso ao Xcode.

Formatadores e filtros: personalização de saída

Os formatadores (DDLogFormatter) — são um protocolo que define como uma mensagem de log é transformada em string antes de ser passada ao logger. O formatador incorporado DDDispatchQueueLogFormatter adiciona o nome da fila de despacho — isso simplifica o rastreio de operações multithread.

// Formatador personalizado com cor e hora
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)"
    }
}

// Aplicação do formatador
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Os filtros (DDLogFilter) — são um protocolo que permite filtrar mensagens no nível do logger. O filtro incorporado DDLoggingContextSetFilter só passa mensagens com um contexto específico (por exemplo, apenas logs de rede). Um filtro personalizado pode analisar o conteúdo da mensagem, nível, tag ou qualquer outro atributo.

A combinação de formatador e filtro em cada logger oferece flexibilidade de nível empresarial. Por exemplo, o DDFileLogger pode usar um formatador detalhado (com timestamp, nível, arquivo, função) e um filtro de “apenas Error”, enquanto o DDOSLogger usa um formatador breve e um filtro de “todos os níveis”.

CocoaLumberjack vs OSLog: comparação de abordagens

OSLog é o sistema de logging incorporado da Apple apresentado no iOS 10 e macOS 10.12. O OSLog funciona no nível do kernel, estrutura logs em formato binário e fornece filtragem incorporada através do Console.app. CocoaLumberjack é uma biblioteca de terceiros que opera no nível da aplicação.

Quando usar OSLog: para logging básico do sistema quando não são necessários logs de arquivo e formatos personalizados. OSLog é a escolha certa para logging a nível de SO onde a integração com Console.app e Instruments é importante.

Quando usar CocoaLumberjack: para aplicativos de produção que precisam de logs de arquivo, rotação, múltiplos canais de saída, formatadores personalizados e desempenho superior a 2.500 mensagens por segundo. CocoaLumberjack também suporta Swift Concurrency (async/await) a partir da versão 3.8.0.

Muitos aplicativos de produção combinam ambas as abordagens: OSLog para logging do sistema (via DDOSLogger como um dos loggers) e DDFileLogger para logs de produção com rotação e acesso do dispositivo.