Swiftpack.co - Package - CocoaLumberjack/CocoaLumberjack

CocoaLumberjack

Unit Tests Pod Version Carthage compatible Pod Platform Pod License codecov codebeat badge

CocoaLumberjack is a fast & simple, yet powerful & flexible logging framework for macOS, iOS, tvOS and watchOS.

How to get started

First, install CocoaLumberjack via CocoaPods, Carthage, Swift Package Manager or manually. Then use DDOSLogger for iOS 10 and later, or DDTTYLogger and DDASLLogger for earlier versions to begin logging messages.

CocoaPods

platform :ios, '9.0'

target 'SampleTarget' do
  use_frameworks!
  pod 'CocoaLumberjack/Swift'
end

Note: Swift is a subspec which will include all the Obj-C code plus the Swift one, so this is sufficient. For more details about how to use Swift with Lumberjack, see this conversation.

For Objective-C use the following:

platform :ios, '9.0'

target 'SampleTarget' do
    pod 'CocoaLumberjack'
end

Carthage

Carthage is a lightweight dependency manager for Swift and Objective-C. It leverages CocoaTouch modules and is less invasive than CocoaPods.

To install with Carthage, follow the instruction on Carthage

Cartfile

github "CocoaLumberjack/CocoaLumberjack"

Swift Package Manager

As of CocoaLumberjack 3.6.0, you can use the Swift Package Manager as integration method. If you want to use the Swift Package Manager as integration method, either use Xcode to add the package dependency or add the following dependency to your Package.swift:

.package(url: "https://github.com/CocoaLumberjack/CocoaLumberjack.git", from: "3.7.0"),

Note that you may need to add both products, CocoaLumberjack and CocoaLumberjackSwift to your target since SPM sometimes fails to detect that CocoaLumerjackSwift depends on CocoaLumberjack.

Install manually

If you want to install CocoaLumberjack manually, read the manual installation guide for more information.

Swift Usage

Usually, you can simply import CocoaLumberjackSwift. If you installed CocoaLumberjack using CocoaPods, you need to use import CocoaLumberjack instead.

DDLog.add(DDOSLogger.sharedInstance) // Uses os_log

let fileLogger: DDFileLogger = DDFileLogger() // File Logger
fileLogger.rollingFrequency = 60 * 60 * 24 // 24 hours
fileLogger.logFileManager.maximumNumberOfLogFiles = 7
DDLog.add(fileLogger)

...

DDLogVerbose("Verbose")
DDLogDebug("Debug")
DDLogInfo("Info")
DDLogWarn("Warn")
DDLogError("Error")

Obj-C usage

If you're using Lumberjack as a framework, you can @import CocoaLumberjack;. Otherwise, #import <CocoaLumberjack/CocoaLumberjack.h>

[DDLog addLogger:[DDOSLogger sharedInstance]]; // Uses os_log

DDFileLogger *fileLogger = [[DDFileLogger alloc] init]; // File Logger
fileLogger.rollingFrequency = 60 * 60 * 24; // 24 hour rolling
fileLogger.logFileManager.maximumNumberOfLogFiles = 7;
[DDLog addLogger:fileLogger];

...

DDLogVerbose(@"Verbose");
DDLogDebug(@"Debug");
DDLogInfo(@"Info");
DDLogWarn(@"Warn");
DDLogError(@"Error");

swift-log backend

CocoaLumberjack also ships with a backend implementation for swift-log. Simply add CocoaLumberjack as dependency to your SPM target (see above) and also add the CocoaLumberjackSwiftLogBackend product as dependency to your target.

You can then use DDLogHandler as backend for swift-log, which will forward all messages to CocoaLumberjack's DDLog. You will still configure the loggers and log formatters you want via DDLog, but writing log messages will be done using Logger from swift-log.

In your own log formatters, you can make use of the swiftLogInfo property on DDLogMessage to retrieve the details of a message that is logged via swift-log.

More information

  • read the Getting started guide, check out the FAQ section or the other docs
  • if you find issues or want to suggest improvements, create an issue or a pull request
  • for all kinds of questions involving CocoaLumberjack, use the Google group or StackOverflow (use #lumberjack).

CocoaLumberjack 3

Migrating to 3.x

  • To be determined

Features

Lumberjack is Fast & Simple, yet Powerful & Flexible.

It is similar in concept to other popular logging frameworks such as log4j, yet is designed specifically for Objective-C, and takes advantage of features such as multi-threading, grand central dispatch (if available), lockless atomic operations, and the dynamic nature of the Objective-C runtime.

Lumberjack is Fast

In most cases it is an order of magnitude faster than NSLog.

Lumberjack is Simple

It takes as little as a single line of code to configure lumberjack when your application launches. Then simply replace your NSLog statements with DDLog statements and that's about it. (And the DDLog macros have the exact same format and syntax as NSLog, so it's super easy.)

Lumberjack is Powerful:

One log statement can be sent to multiple loggers, meaning you can log to a file and the console simultaneously. Want more? Create your own loggers (it's easy) and send your log statements over the network. Or to a database or distributed file system. The sky is the limit.

Lumberjack is Flexible:

Configure your logging however you want. Change log levels per file (perfect for debugging). Change log levels per logger (verbose console, but concise log file). Change log levels per xcode configuration (verbose debug, but concise release). Have your log statements compiled out of the release build. Customize the number of log levels for your application. Add your own fine-grained logging. Dynamically change log levels during runtime. Choose how & when you want your log files to be rolled. Upload your log files to a central server. Compress archived log files to save disk space...

This framework is for you if:

  • You're looking for a way to track down that impossible-to-reproduce bug that keeps popping up in the field.
  • You're frustrated with the super short console log on the iPhone.
  • You're looking to take your application to the next level in terms of support and stability.
  • You're looking for an enterprise level logging solution for your application (Mac or iPhone).

Documentation

Requirements

The current version of Lumberjack requires:

  • Xcode 12 or later
  • Swift 5.3 or later
  • iOS 9 or later
  • macOS 10.10 or later
  • watchOS 3 or later
  • tvOS 9 or later

Backwards compatibility

  • for Xcode 11 and Swift up to 5.2, use the 3.6.2 version
  • for Xcode 10 and Swift 4.2, use the 3.5.2 version
  • for iOS 8, use the 3.6.1 version
  • for iOS 6, iOS 7, OS X 10.8, OS X 10.9 and Xcode 9, use the 3.4.2 version
  • for iOS 5 and OS X 10.7, use the 3.3 version
  • for Xcode 8 and Swift 3, use the 3.2 version
  • for Xcode 7.3 and Swift 2.3, use the 2.4.0 version
  • for Xcode 7.3 and Swift 2.2, use the 2.3.0 version
  • for Xcode 7.2 and 7.1, use the 2.2.0 version
  • for Xcode 7.0 or earlier, use the 2.1.0 version
  • for Xcode 6 or earlier, use the 2.0.x version
  • for OS X < 10.7 support, use the 1.6.0 version

Communication

  • If you need help, use Stack Overflow. (Tag 'lumberjack')
  • If you'd like to ask a general question, use Stack Overflow.
  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request.

Author

  • Robbie Hanson
  • Love the project? Wanna buy me a coffee? (or a beer :D) donation

Collaborators

License

  • CocoaLumberjack is available under the BSD 3 license. See the LICENSE file.

Extensions

Architecture

Github

link
Stars: 12141

Dependencies

Used By

Total: 0

Releases

[3.7.0]: Xcode 12 & Swift 5.3, swift-log - 2020-10-01 15:21:49

Public

  • Breaking change: Dropped support for iOS 8 (#1153)
  • Update SPM tools-version to 5.3 to enable Swift 5.3 support (#1148)
  • Add backend for swift-log (#1164)
  • Specify CocoaPods version to ensure swift_version attribute works (#1167)
  • Simplify DDLogFileManager callbacks for archived log files (#1166)

[3.6.2]: Xcode 11.4+ & Swift 5.2 support, various fixes - 2020-07-31 11:46:38

Public

  • Fix warnings when building with SPM bundled with Swift 5.2 / Xcode 11.4 (#1132)
  • Added Swift name for DDQualityOfServiceName constants.
  • Don't localize timestamps in DDefaultFileLogFormatter (#1151)
  • Allow logging arbitrary objects via Swift log functions (#1146)

Repository

  • Switch from Travis to GitHub Actions (#1135, #1140, #1150, #1152)

Refined Swift interface, improved error handling and bug fixes - 2020-02-03 16:08:38

Public

  • Improve error handling during log file creation in DDFileLogger & DDLogFileManager (#1103 / #1111)
  • Improve nullability annotations in public headers (#1111 / #1112 / #1119)
  • Added support for thread QOS in DDLogMessage class (#1124)

Internal

  • Fix rolling timer being rescheduled rapidly due to leeway (#1106 / #1107)
  • Fix -didArchiveLogFile: returning the file name instead of the file path (#1078)
  • Fix setxattr() function usage (#1118)
  • Fix NSDateFormatter thread safety (#1121)
  • Fix -lt_dataForMessage: duplicated code (#1122)

Xcode 11 and SwiftPM - 2019-10-01 12:01:50

Public

  • Swift Package Manager Support (#1083)
  • New willLogMessage: and didLogMessage: methods on DDFileLogger which provide access to the current log file info (#1076)

Internal

  • Fix issue with log archiving in the simulator (#1098)
  • Limit assertion to non-simulator build (#1100)

Xcode 10.2, Swift 5.0 - 2019-04-24 13:04:52

Public

  • Additional compatibility with Swift 5 (backwards compatible with Swift 4) (#1043)
  • Fix warning building with Xcode 10.2 (#1059)
  • Set Xcode 10.2 and Swift 5.0 as a default (#1064)
  • Fix format string crash (#1066)

Internal

  • Fix warning about syntax (#1054) (#1065)
  • Remove banned APIs (#1056) (#1057)
  • Add CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER & fix warnings (#1059)
  • Use LLONG_MAX instead of LONG_LONG_MAX (#1062)

3.5 Patch2, Swift 5 Compatible, and more - 2019-03-15 12:58:31

Public

  • Fix reusing of log files after rolling (#1042)
  • Fix creation of too many log files (#1049)
  • Preliminary compatibility with Swift 5 (backwards compatible with Swift 4) (#1044)
  • core: loggers os logger variations have been added (#1039)

Internal

  • Sync internal queues to prevent cleaning up log files too soon in tests (#1053)
  • DDLog checks for NULL values and for global queue dispatching has been added (#1045)

3.5 Patch - 2019-02-04 09:10:36

Public

  • Fix high CPU usage because of empty fileAttributes and / or too high rollingFrequceny (#1028 #1033)

Xcode 10 and more - 2019-01-25 10:25:39

Public

  • Added logFileHeader property to DDLogFileManagerDefault. Override to set header for each created file. #998
  • DDFileLogger now accepts a dispatch_queue_t which it uses to run callbacks. If not provided, the default global queue is used. #1003
  • Added opt-in buffering to DDFileLogger. Call wrapWithBuffer to create a file logger which buffers. #1001, #1012
  • Add DDAssert and DDAssertionFailure functions for Swift #934
  • Add DD_LOG_LEVEL define (which can be set in GCC_PREPROCESSOR_DEFINITIONS) for Swift to set default log level (enables stripping for strings that are not logged). #952
  • Add asyncLoggingEnabled global variable to control asynchronous logging. #1019

Internal

  • Prevent memory access errors caused by a failed fetch #944
  • Fix common warnings emitted by -Wall, -Wconversion, -Wextra, etc #943, #931
  • Fixes issue that could cause log messages to become interleaved when there are multiple DDFileLoggers #985
  • DispatchQueueFormatter knows about com.apple.root.default-qos.overcommit now #932
  • Fix thread safety issues in DDFileLogger. Makes it a little harder to deadlock in some cases. #986, #1003, #946
  • Fix availability checks and memory leak #996

Repository

  • Reduce podspec to two subspecs and remove customized modulemap #976
  • Add danger support for PR checks #962 - fixes #956
  • Merged framework targets + using xcconfig + deployment target iOS 8 and Mac OS 10.10 #959 e97da34
  • Documentation update #955 e7414ae 0239196 #933
  • Full links to Docs and other resources so they are resolved on external pages (i.e. https://cocoapods.org/pods/CocoaLumberjack) e9d6971
  • Replace OSAtomic with stdatomic in DDDispatchQueueLogFormatter #957 #958
  • Add Stale Bot + configuration #953
  • Update to Xcode 10 and Swift 4.2 compiler #950
  • Xcode 10 scheme changes #949
  • Update incomplete BSD 3-Clause License #942
  • Updated to CocoaPods 1.5.3 2d0590f
  • Use Xcode 9.4 image for tests #939
  • Xcode (schemes) version bumps #938
  • Update demo and documentation about CustomLogLevels #1023

Xcode 9.3 - 2018-04-17 13:28:33

  • Update README.md #912
  • Fixed typo in pull request template #913
  • Fix -Wimplicit-retain-self warnings #915
  • Update memory management in dynamic logging #916
  • Xcode 9.3 support #921 #923 #926 #927
  • Add extern "C" for Objective-C++ #922
  • Add flush method to the DDFileLogger #928

Xcode 9.2 - 2018-01-26 13:23:03

  • Fix DDLogFileManagerDefault -isLogFile #909
  • Fix locking the main thread #911

Xcode 9.1 - 2018-01-03 18:25:42

  • Fix Travis CI #895
  • Fix typos #896
  • Fix schemes and link errors #897 #899 #903 #907

Xcode 9, Swift 4 - 2017-10-03 16:21:51

• Fix CocoaLumberjackSwift-iOS #890. • Replace OSSpinLock with pthread_mutex #889. • Update to Swift 4 #893. • Build and analyzer warning fixes.

Xcode 9 beta - 2017-08-21 17:16:10

  • Xcode 9 beta support #874 #873 #884 #883 #882
  • Fixed some issues around deleting log files #868 #879
  • update 'Use Log Level per Logger' doc #888
  • Remove empty asset catalogs so that they don't show up in Open Quickly #877
  • Fixed typo in pull request template #880

Xcode 8.3, Swift 3.0.0 - 2017-05-03 09:13:23

  • Xcode 8.3 support #860 #853
  • added a very basic os_log (unified logging) logger #850 #856
  • Use NSFileProtectionType instead of NSString #866
  • Optimized timestamp calculation in DDTTYLogger #851
  • Updated docs #864
  • Fix Travis #863
  • Fixed nullability of DDLogMessage.function #849 DDExtractFileNameWithoutExtension #845
  • Ignore Carthage/Build directory #862
  • Updated schemes #859 #857

Swift 3.0.1, Xcode 8.1 - 2017-02-22 16:23:58

  • Swift 3.0.1 and Xcode 8.1 support via #816
  • Fix Carthage build and updated the podspec structure #819 #818 #784 #790 #782 #778 #815
  • Fix CLIColor.h not included in umbrella header #781 #796 #813 #783
  • Fix crash in [DDLog log:level:flag:context:file:function:line:tag:format:] #831 #830
  • Code improvements:
    • using class properties #779
    • nullability #803 #809 #776
    • fix static analyzer issues #822 #828
    • optimized USE_DISPATCH_CURRENT_QUEUE_LABEL and USE_DISPATCH_GET_CURRENT_QUEUE macros #829
    • fixed dispatch_source_set_timer() usage #834
    • fixed misuse of non null parameter in DDFileLogger fileAttributes #835
    • store calendar in logger queue specifics for multi-thread safety #837
    • reenable default init method for DDLogMessage class #838
  • Added option to not copy messages #832
  • Added new hooks when adding loggers and formatters #836
  • Ability to create new log files every day #736
  • Skip messages in ASL logger which are filtered out by the formatter #786 #742
  • Fixed #823 by adding a hash implementation for DDFileLogger - same as isEqual, it only considers the filePath 7ceed08
  • Fix Travis CI build #807
  • Updated docs #798 #808 #811 #810 #820

Swift 3.0, Xcode 8 - 2016-09-21 11:19:46

  • Swift 3.0 and Xcode 8 support via #769, fixes #771 and #772. Many thanks to @ffried @max-potapov @chrisdoc @BarakRL @devxoul and the others who contributed

Swift 2.3 - 2016-09-19 10:00:08

  • Swift 2.3 explicit so that the project compiles on Xcode 8 - #747 #773 fix #762 #763 #766
  • CocoaPods 1.0.0 fully adopted - 0f5a793 637dfc1 70439fe #729
  • Fix CLIColor.h not found for non-AppKit binaries w/o clang modules #745
  • Retrieve the DDLogLevel of each logger associated to DDLog #753
  • updated doc: #727 a9f54c9 #741, diagrams in 8bd128d
  • Added CONTRIBUTING, ISSUE and PULL_REQUEST TEMPLATE and added a small Communication section to the Readme
  • Fixed an issue with one demo #760

Swift 2.2, Xcode7.3 - 2016-05-02 07:36:12

  • Updated to Swift 2.2 - #704
    • replaced deprecated __FUNCTION__, __FILE__, __LINE__ with newly added to Swift 2.2: #function, #file, #line
  • Xcode 7.3 update - #692 #662
  • simplify usage and integration of the static library target - #657
  • DDLog usable via instances - #679
  • Swift cleanup - #649
  • Enable Application extension API only for tvOS - #701
  • Added appletvos and appletvsimulator to SUPPORTED_PLATFORMS and set TVOS_DEPLOYMENT_TARGET - #707
  • fixed OSSpinLock init issue - #653
  • Added check to prevent duplicate loggers - #682
  • fixed typo in import - #693
  • updated the docs - #646 #650 #656 #655 #661 #664 #667 #684 #724

tvOS, Xcode 7.1 - 2015-10-28 15:26:54

  • added tvOS support (thanks @sinoru) - #634 #640 #630 #628 #618 #611
  • Remove (escaping) from the Swift @autoclosure parameters - #642

Swift 2.0, WatchOS, Xcode7 - 2015-10-23 14:39:50

  • Fixed the version for the Carthage builds - see #633
  • Improved documentation
  • Includes changes from 2.1.0 Beta and 2.1.0 RC

2.1.0 RC - Swift 2.0, WatchOS, Xcode7 - 2015-10-22 13:08:08

  • Refactored the NSDateFormatter related code to fix a bunch of issues: #621
  • Fix Issue #488: Support DDLog without AppKit Dependency (#define DD_CLI): #627
  • Re-add NS_DESIGNATED_INITIALIZER #619

Patch for 2.0.0 - 2015-10-13 07:04:10

Compatibility with Xcode 6 that was broken by the 2.0.2 patch - f042fd3

2.1.0 Beta - Swift 2.0, WatchOS, Xcode7 - 2015-10-12 20:54:31

  • Updated the library to use Swift 2.0 and Xcode 7 #617 #545 #534
  • WatchOS support (2.0) #583 #581 #579

Patch for 2.0.0 - 2015-10-12 20:30:09

  • Swift 1.2 fixes #546 #578 plus and update to Swift 2.0 5627dff imported from our swift_2.0 branch
  • Make build work on tvOS #597
  • Make CocoaLumberjackSwift-iOS target depends on CocoaLumberjack-iOS #575
  • APPLICATION_EXTENSION_API_ONLY to YES for Extensions #576
  • Remove unnecessary NS_DESIGNATED_INITIALIZERs #593 fixes #592
  • Add ignore warning mark for DDMakeColor #553
  • Kill unused function warnings from DDTTYLogger.h #613
  • Flag unused parameters as being unused to silence strict warnings #566
  • Extend ignore unused warning pragma to cover all platforms #559
  • Removed images.xcassets from Mobile project #580
  • Silence the Xcode 7 upgrade check - #595
  • Fix import for when CL framework files are manually imported into project #560
  • Don't override defines in case they're already set at project level #551
  • log full filepath when failing to set attribute #550
  • Fix issue in standalone build with DDLegacyMacros.h #552
  • Update CustomFormatters.md with proper thread-safe blurb #555
  • typo in parameter's variable name fixed #568
  • Typo: minor fix #571
  • Surely we should be adding 1, not 0 for OSAtomicAdd32 ? #587
  • rollLogFileWithCompletionBlock calls back on background queue instead of main queue #589
  • Removing extraneous \ on line 55 #600
  • Updated GettingStarted.md to include ddLogLevel #602
  • Remove redundant check for processorCount availability #604

Patch for 2.0.0 - 2015-06-24 21:23:17

  • Carthage support #521 #526
  • fixed crash on DDASLLogCapture when TIME or TIME_NSEC is NULL #484
  • Swift fixes and improvements: #483 #509 #518 #522 5eafceb
  • Unit tests: #500 #498 #499
  • Fix #478 by reverting #473
  • Add armv7s to static library #538
  • Fix NSLog threadid mismatch with iOS 8+/OSX 10.10+ #514
  • Fixed the LogV macros so that avalist is no longer undefined #511
  • Using type safe DDColor alias instead of #define directive #506
  • Several fixes/tweaks to DDASLLogCapture #512
  • Prevent duplicate log entries when both DDASLLogCapture and DDASLLogger are used #515
  • Fix memory leaks in DDTTYLogger, add self annotations to blocks #536
  • Update older syntax to modern subscripting for array access #482
  • Remove execute permission on non-executable files #517
  • Change code samples to use DDLogFlagWarning #520
  • Fix seemingly obvious typo in the toLogLevel function #508

CocoaLumberjack 2.0.0 - 2015-03-13 14:40:27

CocoaLumberjack 2.0.0

The library was strongly refactored, with a few goals in mind:

  • Swift support - that we will release in a separate milestone, since CocoaPods 0.36.0 just got out
  • Unit tests support
  • reorganised things (on disk)
  • better coding style

See Migration from 1.x to 2.x

2.0.0-rc2 - 2015-02-20 06:04:59

  • Bucket of Swift improvements - #434 #437 #449 #440
  • Fixed #433 (build issue due to dispatch_queue properties) - #455
  • Enable codesign for iOS device framework builds - #444
  • Declare automaticallyAppendNewlineForCustomFormatters properties as nonatomic - #443
  • Warning fixes & type standardization - #419
  • Legacy checks updated - #424
  • Documentation updates

2.0.0-rc - 2014-12-11 09:39:33

  • Fix dispatch_queue_t properties.
  • Fix registeredClasses crashes at launch.

2.0.0-beta4 - 2014-11-07 02:59:23

  • Major refactoring and clean up.
  • Remove superfluous log from property names and use underscore for direct variable access.
  • Preliminar Swift support through CocoaLumberjack.swift.
  • Automatic 1.9.x legacy support when DDLog.h is imported instead of the new CocoaLumberjack.h.

2.0.0-beta3 - 2014-10-21 01:47:09

  • Modernize flag variables to be NS_OPTIONS/NS_ENUM.
  • Change the log flags and levels to NSUInteger.
  • Fix warning when compiled with assertions blocked.
  • Crash fixes.