logging-concepts.md

Logging Concepts (platform-agnostic)

This file is shared by mobile-logging-android and mobile-logging-ios. Platform-specific code lives in each skill's SKILL.md.

Log domains

Domain	What it covers
DATABASE	Document CRUD, index operations
QUERY	Query compilation and execution
REPLICATOR	Sync connection, push/pull, conflicts
NETWORK	WebSocket frames, TLS handshake
LISTENER	P2P listener events

Log levels

DEBUG > VERBOSE > INFO > WARNING > ERROR > NONE

Use DEBUG only during development — it generates significant output and impacts performance. Use WARNING or ERROR in production.

cbl-log tool

The cbl-log tool decodes binary log files written by the file sink.

# Download from https://github.com/couchbaselabs/cbl-log/releases
cbl-log logcat --log /path/to/cbl_log_*.cbllog

Binary logs are more efficient than plain text and are the recommended format for production diagnostics. Share binary logs with Couchbase support when filing issues.

What to log for common issues

Issue	Domain	Level
Sync not starting	REPLICATOR	DEBUG
Documents not appearing	REPLICATOR + DATABASE	DEBUG
Query returning wrong results	QUERY	DEBUG
TLS / certificate errors	NETWORK	DEBUG
Performance problems	DATABASE + QUERY	VERBOSE