Using Logs for Troubleshooting


    Description — Couchbase Lite on Java — Using Logs for Troubleshooting
    Related Content — Troubleshooting Queries

    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
    final File path = new File("/usr/local/MyApp/logs")
    Database.log.getFile().setConfig(new LogFileConfiguration(path.toString()));

    Replication Logging

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

    Example 2. Setting replication log-level
    Database.setLogLevel(LogDomain.REPLICATOR, LogLevel.VERBOSE);

    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
    class LogTestLogger implements Logger {
        private final LogLevel level;
        public LogTestLogger(@NonNull LogLevel level) { this.level = level; }
        public LogLevel getLevel() { return level; }
        public void log(@NonNull LogLevel level, @NonNull LogDomain domain, @NonNull String message) {
            // this method will never be called if param level < this.level
            // handle the message, for example piping it to a third party framework
    Example 4. Enabling custom logging
    // this custom logger will never be asked to log an event
    // with a log level < WARNING
    Database.log.setCustom(new LogTestLogger(LogLevel.WARNING));

    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