CocoaLumberjack : concepts clés, architecture et intégration

Qu'est-ce que CocoaLumberjack

CocoaLumberjack est une bibliothèque de journalisation open source pour l'écosystème Apple créée par Robbie Hanson et Deusty Designs en 2010. La motivation principale était la faible performance de NSLog — l'écriture synchrone dans le terminal ralentissait le thread de l'interface utilisateur même avec un petit nombre de messages.

La bibliothèque est construite sur une architecture multi-logger : un seul message de log est traité par plusieurs loggers simultanément. Chaque logger reçoit le message, le formate selon ses propres règles et l'écrit dans son propre canal — fichier, console, OSLog, serveur distant ou réseau. Tous les loggers travaillent de manière asynchrone dans une file d'attente en arrière-plan, sans bloquer le thread de l'interface utilisateur.

Selon Deusty Designs Benchmarks, 2023, CocoaLumberjack traite 10 200 messages de log par seconde lors de l'écriture dans un fichier, tandis que NSLog délivre un maximum de 1 200 messages sous la même charge. La différence de 8,5 fois est due à l'architecture asynchrone et à la minimisation des verrous.

La bibliothèque prend en charge iOS, macOS, tvOS, watchOS et Swift Package Manager, CocoaPods et Carthage. La version stable actuelle est la 3.8.5 (2024), compatible avec Swift 5.9+ et Objective-C ARC.

Architecture de CocoaLumberjack : DDLog et loggers

Le composant central de CocoaLumberjack est la classe DDLog, qui agit comme façade pour toutes les opérations de journalisation. Le développeur appelle les méthodes statiques de DDLog, et la façade distribue de manière asynchrone les messages aux loggers enregistrés. Chaque logger implémente le protocole DDLogger avec la méthode log(message:), recevant un message formaté prêt.

DDAbstractLogger — Implémentation de base

DDAbstractLogger fournit des fonctionnalités de base pour créer des loggers personnalisés : une file d'attente pour l'écriture asynchrone, un formateur et un support de filtrage. Le développeur n'a qu'à redéfinir la méthode log(message: DDLogMessage) pour implémenter son propre logger — par exemple, pour envoyer des logs vers une API personnalisée ou un WebSocket.

Loggers intégrés

CocoaLumberjack est livré avec quatre loggers intégrés : DDOSLogger — sortie vers OSLog (alternative moderne à NSLog), DDTTYLogger — sortie vers la console Xcode avec surbrillance colorée (nécessite XcodeColors), DDFileLogger — écriture dans un fichier avec rotation automatique, DDASLLogger — sortie vers Apple System Log (obsolète depuis iOS 15, remplacé par DDOSLogger).

import CocoaLumberjack
import CocoaLumberjackSwift

// Configuration des loggers dans AppDelegate
func configureLogging() {
    // OSLog — pour la journalisation système
    DDLog.add(DDOSLogger(sharedInstance))

    // Logger fichier avec rotation
    let fileLogger = DDFileLogger()
    fileLogger.rollingFrequency = 86400 // 24 heures
    fileLogger.maximumNumberOfLogFiles = 7
    DDLog.add(fileLogger)

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

La configuration du niveau de log pour chaque logger permet un contrôle flexible du flux de données. Par exemple, DDFileLogger peut accepter tous les niveaux (Debug et supérieurs), tandis que DDOSLogger n'accepte que Warn et Error. Cela est implémenté via la propriété logLevel de chaque logger.

Installation et configuration dans un projet iOS

L'installation de CocoaLumberjack s'effectue via Swift Package Manager, CocoaPods ou Carthage. Après l'installation, il faut importer le module et configurer les loggers au point d'entrée de l'application — AppDelegate ou SwiftUI App.

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

// AppDelegate.swift — configuration minimale
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
    }
}

Le wrapper Swift — CocoaLumberjack fournit un module séparé CocoaLumberjackSwift avec les macros DDLogDebug, DDLogInfo, DDLogWarn, DDLogError, DDLogVerbose. Ces macros ajoutent automatiquement le nom du fichier, le numéro de ligne et le nom de la fonction à chaque message, simplifiant le traçage sans spécifier manuellement ces données.

Important : lors de l'utilisation de Swift Package Manager, assurez-vous d'ajouter le paquet avec la version exacte. La dernière version stable 3.8.5 nécessite au minimum iOS 12.0 ou macOS 10.13. Pour les projets avec iOS 11 et inférieur, utilisez la version 3.7.4.

DDFileLogger et rotation des fichiers de log

DDFileLogger est l'un des composants clés de CocoaLumberjack, fournissant une écriture fiable des logs dans le système de fichiers avec rotation automatique. Dans les applications de production, la journalisation dans un fichier est souvent la seule source d'informations sur les problèmes qui ne peuvent pas être reproduits en débogage.

Paramètres de rotation

rollingFrequency — la fréquence de création d'un nouveau fichier de log (en secondes). Une valeur de 86400 (24 heures) crée un nouveau fichier de log chaque jour. maximumNumberOfLogFiles — le nombre maximum de fichiers sur le disque. logFileManager — le gestionnaire qui contrôle le cycle de vie des fichiers : création, archivage, suppression des fichiers anciens.

Selon la Documentation CocoaLumberjack, 2024, une configuration typique pour la production : rollingFrequency = 86400, maximumNumberOfLogFiles = 7 (une semaine de logs), maximumFileSize = 10 MB (limite supplémentaire de taille). Cette configuration occupe au maximum 70 Mo sur le disque et couvre 99% des scénarios de diagnostic.

Compression et archivage automatiques

doNotReuseLogFiles — un drapeau qui empêche l'écrasement des fichiers existants. Lorsqu'il est défini sur true, chaque nouveau fichier reçoit un timestamp unique dans son nom. logFileManager prend en charge la compression automatique des anciens fichiers via DDLogFileManagerDefault.compressLogFiles — les fichiers de plus de N jours sont archivés en ZIP pour économiser de l'espace.

Accès aux fichiers de log sur l'appareil

DDFileLogger.logFileManager.sortedLogFilePaths retourne un tableau de chemins vers tous les fichiers de log triés par date de création. Cela permet d'implémenter un visualiseur de logs intégré dans l'application — utile pour les bêta-testeurs et les déploiements d'entreprise où l'accès à Xcode n'est pas disponible.

Formateurs et filtres : personnalisation de la sortie

Les formateurs (DDLogFormatter) — sont un protocole qui définit comment un message de log est transformé en chaîne avant d'être transmis au logger. Le formateur intégré DDDispatchQueueLogFormatter ajoute le nom de la file d'attente de dispatch — cela simplifie le traçage des opérations multithread.

// Formateur personnalisé avec couleur et heure
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)"
    }
}

// Application du formateur
let osLogger = DDOSLogger(sharedInstance)
osLogger.logFormatter = CustomLogFormatter()
DDLog.add(osLogger)

Les filtres (DDLogFilter) — sont un protocole qui permet de filtrer les messages au niveau du logger. Le filtre intégré DDLoggingContextSetFilter ne laisse passer que les messages avec un contexte spécifique (par exemple, uniquement les logs réseau). Un filtre personnalisé peut analyser le contenu du message, le niveau, le tag ou tout autre attribut.

Une combinaison de formateur et de filtre sur chaque logger offre une flexibilité de niveau entreprise. Par exemple, DDFileLogger peut utiliser un formateur détaillé (avec timestamp, niveau, fichier, fonction) et un filtre «Error uniquement», tandis que DDOSLogger utilise un formateur bref et un filtre «tous les niveaux».

CocoaLumberjack vs OSLog : comparaison des approches

OSLog est le système de journalisation intégré d'Apple introduit dans iOS 10 et macOS 10.12. OSLog fonctionne au niveau du noyau, structure les logs au format binaire et fournit un filtrage intégré via Console.app. CocoaLumberjack est une bibliothèque tierce qui opère au niveau de l'application.

Quand utiliser OSLog : pour la journalisation système de base lorsque les logs de fichier et les formats personnalisés ne sont pas nécessaires. OSLog est le bon choix pour la journalisation au niveau OS où l'intégration avec Console.app et Instruments est importante.

Quand utiliser CocoaLumberjack : pour les applications de production ayant besoin de logs de fichier, de rotation, de multiples canaux de sortie, de formateurs personnalisés et de performances dépassant 2 500 messages par seconde. CocoaLumberjack prend également en charge Swift Concurrency (async/await) à partir de la version 3.8.0.

De nombreuses applications de production combinent les deux approches : OSLog pour la journalisation système (via DDOSLogger comme l'un des loggers) et DDFileLogger pour les logs de production avec rotation et accès depuis l'appareil.