Using Logs for Troubleshooting


    Description — Couchbase Lite on Swift — Using Logs for Troubleshooting
    Related Content — Troubleshooting Queries | Decoding Crash Logs

    Couchbase Lite provides a logging API that unifies the logging behavior across all platforms[1], making debugging and troubleshooting easier during development and in production.

    The retrieval of logs from the device is out of scope of this feature.

    Available logging features include:

    • Console based logging

    • File based logging

    • Replication logging

    • Custom logging

    Console based logging

    Default: Enabled.

    Console based logging is often used to facilitate troubleshooting during development.

    File based logging

    Default: Disabled.

    Available file based logging formats:

    • Binary — most efficient for storage and performance. It is the default for file based logging.

    • Plaintext

    We recommend using the binary log format and a decoder, such as cbl-log, to view them. Download cbl-log from couchbaselabs/couchbase-mobile-tools.

    The following example enables file based logging.

    Example 1. Enabling file logging
    let tempFolder = NSTemporaryDirectory().appending("cbllog")
    Database.log.file.config = LogFileConfiguration(directory: tempFolder)
    Database.log.file.level = .info

    Replication Logging

    The following example increases the log output for activity related to replication with Sync Gateway.

    Example 2. Setting replication log-level
    // Replicator
    Database.setLogLevel(.verbose, domain: .replicator)
    // Network
    Database.setLogLevel(.verbose, domain: .network)

    Custom logging

    Default: Disabled.

    Allows registration of a callback function to receive Couchbase Lite log messages, which may be logged using any external logging framework.

    Apps must implement the Logger interface — see Example 3 — a And set it on the custom property — see Example 4.

    Example 3. Implementing logger interface
    fileprivate class LogTestLogger: Logger {
        // set the log level
        var level: LogLevel = .none
        func log(level: LogLevel, domain: LogDomain, message: String) {
            // handle the message, for example piping it to
            // a third party framework
    Example 4. Enabling custom logging
    Database.log.custom = LogTestLogger()

    Decoding binary logs

    You can use the cbl-log tool to decode binary log files — see Example 5.

    Example 5. Using the cbl-log tool
    • macOS

    • CentOS

    • Windows

    Download the cbl-log tool using wget.


    Navigate to the bin directory and run the cbl-log executable.

    $ ./cbl-log logcat LOGFILE <OUTPUT_PATH>

    Download the cbl-log tool using wget.


    Navigate to the bin directory and run the cbl-log executable.

    cbl-log logcat LOGFILE <OUTPUT_PATH>

    Download the cbl-log tool using PowerShell.

    Invoke-WebRequest -OutFile

    Run the cbl-log executable.

    $ .\cbl-log.exe logcat LOGFILE <OUTPUT_PATH>
    Learn more . . .
    Dive Deeper . . .

    1. From version 2.5