Skip to content

Using Logs

Couchbase Lite — Using Logs for Troubleshooting

Constraints

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

Introduction

Couchbase Lite provides a robust Logging API — see API References for Log, FileLogger, and LogFileConfiguration — 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:

  • 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.
  • File based logging

    Here logs are written to separate log files, filtered by log level, with each log level supporting individual retention policies.
  • 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 changes without compromising any file logging streams. It is enabled by default. To change default settings use the Database.log property to set the required values — see Example 1 .

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

Example 1. Change Console Logging Settings

This example enables and defines console-based logging settings.

Database.log.console.domains = LogDomain.ALL_DOMAINS
Database.log.console.level = LogLevel.VERBOSE
  1. Define the required domain; here we turn on logging for all available domains — see ConsoleLogger.domains and enum LogDomain.
  2. Here we turn on the most verbose log level — see ConsoleLogger.level and enum LogLevel.
    To disable logging for the specified LogDomains 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.file and FileLogger to control file-based logging.

Formats

Available file based logging formats:

  • Binary — most efficient for storage and performance. It is the default for file based logging.
    <br. Use this format and a decoder, such as cbl-log, to view them — see Decoding binary logs.
  • Plaintext

Configuration

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

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

  • Path to the directory to store the log files
  • Log file format
    The default is binary. You can override that where necessary and output a plain text log.
  • Maximum number of rotated log files to keep
  • Maximum size of the log file (bytes). Once this limit is exceeded a new log file is started.

Example 2. Enabling file logging

Database.log.file.apply {
    config = LogFileConfigurationFactory.newConfig(
        directory = "temp/cbl-logs",
        maxSize = 10240,
        maxRotateCount = 5,
        usePlainText = false
    )
    level = LogLevel.INFO
}
  1. Set the log file directory
  2. 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. Set the maximum size (bytes) for our log file
  4. Select the binary log format (included for reference only as this is the default)
  5. Increase the log output level from the default (WARNING) to INFO — see FileLogger.level

Tip

"temp/cbl-logs" might be a platform-specific location. Use expect/actual or dependency injection to provide a platform-specific log file path.

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.custom — see Example 4.

Example 3. Implementing logger interface

Here we introduce the code that implements the Logger interface.

class LogTestLogger(override val level: LogLevel) : Logger {
    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
    }
}

Example 4. Enabling custom logging

This example show how to enable the custom logger from Example 3.

// this custom logger will not log an event with a log level < WARNING
Database.log.custom = LogTestLogger(LogLevel.WARNING)

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.

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

Download the cbl-log tool using wget.

console
wget https://packages.couchbase.com/releases/couchbase-lite-log/3.1.1/couchbase-lite-log-3.1.1-macos.zip

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

console
./cbl-log logcat LOGFILE <OUTPUT_PATH>

Download the cbl-log tool using wget.

console
wget https://packages.couchbase.com/releases/couchbase-lite-log/3.1.1/couchbase-lite-log-3.1.1-centos.zip

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

console
./cbl-log logcat LOGFILE <OUTPUT_PATH>

Download the cbl-log tool using PowerShell.

PowerShell
Invoke-WebRequest https://packages.couchbase.com/releases/couchbase-lite-log/3.1.1/couchbase-lite-log-3.1.1-windows.zip -OutFile couchbase-lite-log-3.1.1-windows.zip

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

PowerShell
.\cbl-log.exe logcat LOGFILE <OUTPUT_PATH>