Logging API
Introduced in Couchbase Lite 3.2.2.
LogSinks
Log sinks are thread safe, removing risk of inconsistent states during initialization.
The three destinations for logs have been named as LogSinks, following the common source–sink terminology.
The FileLogSink, the ConsoleLogSink and the CustomLogSink are all to be installed in an instance of LogSinks.
Only ConsoleLogSink is enabled for all logging domains at the warning level by default.
To enable a specific type of log sink, create a log sink object of that type, set its minimum log level and domains, and assign it to LogSinks.
To disable a log sink, set it to null or use a log sink with LogLevel.NONE.
Couchbase still logs its messages in a handful of named domains and at common log levels: LogLevel.DEBUG the most verbose, and LogLevel.ERROR only for serious failures.
Accessing LogSinks depends on the platform.
In Java, use the method LogSinks.get() to obtain an instance.
In Swift, Objective-C, .NET, and C, LogSinks provides only static methods, without a singleton instance.
LogSinks are immutable: you set the level and domain at which they log in their constructors.
For example, you can only change the level at which the ConsoleLogSink forwards messages to the console by installing a new one created for the new log level.
Log output is split into the following streams:
-
Logging to the Couchbase File Log
Each log level writes to a separate file and there is a single retention policy for all files
-
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.
-
For greater flexibility you can implement a custom logging class.
Logging to the Console
Create an instance of ConsoleLogSink initialized with the desired log level and domains and install it.
LogSinks.console = ConsoleLogSink(level: .verbose, domains: .all)Logging to the Couchbase File Log
Create a new FileLogSink with the desired properties and install it.
setRotateCount from before 3.2.2 API is slightly different from setMaxKeptFiles.
setMaxKeptFiles is the maximum number of log files that will exist at any time and is the count of rotated files (setRotateCount) plus one.
|
let tempFolder = NSTemporaryDirectory().appending("cbllog")
LogSinks.file = FileLogSink(level: .verbose, directory: tempFolder, usePlainText: false, maxKeptFiles: 12, maxFileSize: 524288)Using a Custom Logger
Create an instance of your custom sink, and to install it use LogSinks.get().setCustom in Java, or the appropriate static method in Swift, Objective-C, .NET, and C.
As with the other log sinks, you will have to specify the level and domain at which Couchbase logs are forwarded to your custom sink at its creation.
Your custom log sink code will have to change as well. In Swift, which lacks abstract methods, a custom log sink implements LogSinkProtocol and is assigned to a CustomLogSink instance during creation.
Your logger will receive only logs at the level and domain for which it is initialized.
There is no need to record or filter the logs forwarded to the protected writeLog method.
LogSinks are meant to support logging by the Couchbase Lite platform. They were never meant as a general framework for logging.
| Customer code can no longer log, directly, to any of the Couchbase log sinks. The Console and File log sinks cannot be subclassed and do not publish methods that allow writing logs. If you need to log to the console for example, you’ll have to create your own way of doing so. |
class TestLogSink: LogSinkProtocol {
func writeLog(level: LogLevel, domain: LogDomain, message: String) {
// handle the message, for example piping it to
// a third party framewor
} LogSinks.custom = CustomLogSink(level: .warning, logSink: TestLogSink())Decoding binary logs
The latest version of the cbl-log tool is 3.0.0.
|
You can use the cbl-log tool to decode binary log files — see Example 1.
-
macOS
-
CentOS
-
Windows
Download the cbl-log tool using wget.
wget https://packages.couchbase.com/releases/couchbase-lite-log/3.0.0/couchbase-lite-log-3.0.0-macos.zipNavigate to the bin directory and run the cbl-log executable.
$ ./cbl-log logcat LOGFILE <OUTPUT_PATH>Download the cbl-log tool using wget.
wget https://packages.couchbase.com/releases/couchbase-lite-log/3.0.0/couchbase-lite-log-3.0.0-centos.zipNavigate 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 https://packages.couchbase.com/releases/couchbase-lite-log/3.0.0/couchbase-lite-log-3.0.0-windows.zip -OutFile couchbase-lite-log-3.0.0-windows.zipRun the cbl-log executable.
$ .\cbl-log.exe logcat LOGFILE <OUTPUT_PATH>