CocoaLumberjack for Apple

Integrate CocoaLumberjack with Sentry to capture and send structured logs.

The SentryCocoaLumberjack package provides a CocoaLumberjack logger that forwards log entries to Sentry's structured logging system. Once configured, any logs emitted through CocoaLumberjack are automatically captured and sent to Sentry with full context, including source location, thread information, and log levels.

  • Sentry Cocoa SDK 9.27.0 or above
  • CocoaLumberjack 3.8.0 or above

Add the package via Swift Package Manager:

Copied
dependencies: [
    .package(url: "https://github.com/getsentry/sentry-apple-cocoalumberjack", from: "9.0.0")
]

Or add it in Xcode via File > Add Package Dependencies using the URL https://github.com/getsentry/sentry-apple-cocoalumberjack.

By default, the integration uses precompiled Sentry binary xcframeworks. If you need to build Sentry from source, enable the SentryFromSource trait:

Copied
dependencies: [
    .package(url: "https://github.com/getsentry/sentry-apple-cocoalumberjack", from: "9.0.0", traits: ["SentryFromSource"])
]

Initialize the Sentry SDK, then add SentryCocoaLumberjackLogger to CocoaLumberjack. SDK 9.27.0+ doesn't require an enable flag for logs forwarded by this integration:

Copied
import Sentry
import CocoaLumberjackSwift
import SentryCocoaLumberjack

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
}

// Only logs at .info level and above will be sent to Sentry
DDLog.add(SentryCocoaLumberjackLogger(), with: .info)

Use CocoaLumberjack's built-in filtering when adding the logger to control which messages are sent to Sentry:

Copied
// Only send error logs to Sentry
DDLog.add(SentryCocoaLumberjackLogger(), with: .error)

Copied
import CocoaLumberjackSwift

DDLogInfo("User logged in")
DDLogError("Payment failed")
DDLogWarn("API rate limit approaching")
DDLogDebug("Processing request")
DDLogVerbose("Detailed trace information")

CocoaLumberjack log levels are automatically mapped to Sentry log levels:

CocoaLumberjack LevelSentry Log Level
.error.error
.warning.warn
.info.info
.debug.debug
.verbose.trace

The logger automatically includes the following attributes with every log entry:

AttributeDescription
sentry.origin"auto.logging.cocoalumberjack"
cocoalumberjack.levelThe original CocoaLumberjack log level
code.file.pathThe source file path
code.function.nameThe function name
code.line.numberThe line number
cocoalumberjack.contextThe log context
cocoalumberjack.timestampThe log timestamp
cocoalumberjack.threadIDThe thread ID
cocoalumberjack.threadNameThe thread name (if available)
cocoalumberjack.queueLabelThe dispatch queue label (if available)
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").