Using Logs for Troubleshooting


    Description — Couchbase Lite on Objective-C — 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
    NSString* tempFolder = [NSTemporaryDirectory() stringByAppendingPathComponent:@"cbllog"];
    CBLLogFileConfiguration* config = [[CBLLogFileConfiguration alloc] initWithDirectory:tempFolder];
    [CBLDatabase.log.file setConfig:config];
    [CBLDatabase.log.file setLevel: kCBLLogLevelInfo];

    Replication Logging

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

    Example 2. Setting replication log-level
    // Replicator
    [CBLDatabase setLogLevel:kCBLLogLevelVerbose domain:kCBLLogDomainReplicator];
    // Network
    [CBLDatabase setLogLevel:kCBLLogLevelVerbose domain:kCBLLogDomainNetwork];

    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
    @interface LogTestLogger : NSObject<CBLLogger>
    // set the log level
    @property (nonatomic) CBLLogLevel level;
    @implementation LogTestLogger
    @synthesize level=_level;
    - (void) logWithLevel: (CBLLogLevel)level domain: (CBLLogDomain)domain message: (NSString*)message {
        // handle the message, for example piping it to
        // a third party framework
    Example 4. Enabling custom logging
    [CBLDatabase.log setCustom:[[LogTestLogger alloc] init]];

    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