Using Logs for Troubleshooting


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

    • The value returned by LogLevel.getValue() is not the Android log level. Do not use this API call.

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

    • This content applies to the post 2.5 versions. If you are using a Couchbase Lite release prior to 2.5 see Deprecated functionality


    Couchbase Lite provides a robust Logging API [1] — see: API References for Log, FileLogger and LogFileConfiguration(String directory) — which make debugging and troubleshooting easier during development and in production. It delivers flexibility in terms of how logs are generated and retained, whilst also maintaining the level of logging required by Couchbase Support for investigation of issues.

    Log output is split into the following streams:

    • File based logging

      Here logs are written to separate log files filtered by log level, with each log level supporting individual retention policies.

    • Console based logging

      You can independently configure and control console logs, which provides a convenient method of accessing diagnostic information during debugging scenarios. With console logging, you can fine-tune diagnostic output to suit specific debug scenarios, without interfering with any logging required by Couchbase Support for the investigation of issues.

    • Custom logging

      For greater flexibility you can implement a custom logging class using the Logger interface.

    In all instances, you control what is logged and at what level using the Log class.

    Console based logging

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

    Console logs are your go-to resource for diagnostic information. You can easily fine-tune their diagnostic content to meet the needs of a particular debugging scenario, perhaps by increasing the verbosity and-or choosing to focus on messages from a specific domain; to better focus on the problem area.

    Changes to console logging are independent of file logging, so you can make change without compromising any files logging streams. It is enabled by default. To change default settings use database’s Log method to set the required values — see Example 1

    You will primarily use log.getConsole() and ConsoleLogger to control console logging.

    It can often be more effective to just use the Console logger (which logs to logcat).
    Note, a warning is displayed when you set continuous (file) logging off.
    Example 1. Change Console Logging Settings

    This example enables and defines console-based logging settings.

    • Kotlin

    • Java = LogDomain.ALL_DOMAINS (1)
    Database.log.console.level = LogLevel.VERBOSE (2)
    Database.log.getConsole().setDomain(LogDomain.ALL_DOMAINS);  (1)
    Database.log.getConsole().setLevel(LogLevel.VERBOSE); (2)
    1 Define the required domain ; here we turn on logging for all available domains — see: log.getConsole().setDomain() and enum LogDomain
    2 Here we turn on the most verbose log level — see: log.getConsole().setLevel() and enum LogLevel.
    To disable logging for the specified LogDomain set the LogLevel to None.

    File based logging

    File based logging is disabled by default —  see: Example 2 for how to enable it.

    You will primarily use log.getFile() and FileLogger to control file-based logging.


    Available file based logging formats:

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

      Use this format and a decoder, such as cbl-log, to view them — see: Decoding binary logs.

    • Plaintext


    As with console logging you can set the log level — see: the FileLogger class.

    With file based logging you can also use the LogFileConfiguration(String directory) class’s properties to specify the:

    • log file path to the directory to store the log file Once this limit is exceeded a new log file is started.

    • log file format
      The default is binary. You can over ride that where necessary and output a plain text log.

    • maximum number of rotated log files to keep

    • maximum size of the log file (bytes).

    Example 2. Enabling file logging
    • Kotlin

    • Java

    Database.log.file.let {
      it.config = LogFileConfigurationFactory.create(
        context.cacheDir.absolutePath, (1)
        maxSize = 10240, (2)
        maxRotateCount = 5, (3)
        usePlainText = false
        ) (4)
        it.level = LogLevel.INFO (5)
    final File path = context.getCacheDir();
    LogFileConfiguration LogCfg =
      new LogFileConfiguration(path.toString()); (1)
    LogCfg.setMaxSize(10240); (2)
    LogCfg.setMaxRotateCount(5); (3)
    LogCfg.setUsePlainText(false); (4)
    Database.log.getFile().setLevel(LogLevel.INFO); (5)
    1 Set the log file directory
    2 Here we change the max rotation count from the default (1) to 5.
    Note this means six files may exist at any one time; the five rotated log files, plus the active log file
    3 Here we set the maximum size (bytes) for our log file
    4 Here we select the binary log format (included for reference only as this is the default)
    5 Here we increase the log output level from the default (warnings) to info — see: log.getFile().setLevel()

    Note that the use of Database.setLogLevel() is now deprecated. Further, you can no longer set a log level for a specific domain.

    Custom logging

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

    To do this, apps must implement the Logger interface — see Example 3 — and enable custom logging using log.setCustom() — see Example 4.

    Example 3. Implementing logger interface

    Here we introduce the code that implements the Logger interface.

    • Kotlin

    • Java

    class LogTestLogger(private val level: LogLevel) : Logger {
        override fun getLevel() = level
        override fun log(level: LogLevel, domain: LogDomain, message: String) {
            // this method will never be called if param level < this.level
            // handle the message, for example piping it to a third party framework
    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) {
    Example 4. Enabling custom logging

    This example show how to enable the custom logger from <>.

    • Kotlin

    • Java

    // this custom logger will not log an event with a log level < WARNING
    Database.log.custom = LogTestLogger(LogLevel.WARNING) (1)
    Database.log.setCustom(new LogTestLogger(LogLevel.WARNING)); (1)
    1 Here we set the custom logger with a level of 'warning'. The custom logger is called with every log and may choose to filter it, using its configured level.

    Log | log.getCustom() | Logger

    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>

    Logging functionality prior to Release 2.5

    The pre-Couchbase Lite 2.5 logging functionality is deprecated. It was superseded by an enhanced Logging API in that release. This information is included for completeness only.

    The log messages are split into different domains (LogDomains) which can be tuned to different log levels.

    Example 6. Enable verbose logging on a domain

    The following example enables `verbose` logging for the `replicator` and `query` domains.

    • Kotlin

    • Java

    Database.setLogLevel(LogDomain.DATABASE, LogLevel.VERBOSE);
    Database.setLogLevel(LogDomain.QUERY, LogLevel.VERBOSE);

    1. From version 2.5