Using Logs for Troubleshooting


    Description — Couchbase Lite on C# — 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
    var tempFolder = Path.Combine(Service.GetInstance<IDefaultDirectoryResolver>().DefaultDirectory(), "cbllog");
    Database.Log.File.Config = new LogFileConfiguration(tempFolder);
    Database.Log.File.Level = LogLevel.Info;

    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);
    Database.SetLogLevel(LogDomain.Network, 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
    private class LogTestLogger : ILogger
        public LogLevel Level { get; set; }
        public void Reset()
        public void Log(LogLevel level, LogDomain domain, string message)
            // handle the message, for example piping it to
            // a third party framework
    Example 4. Enabling custom logging
    Database.Log.Custom = new 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