Skip to content

Logging

Jump to bottom
Jens Alfke edited this page Jul 3, 2016 · 10 revisions

There's a fair bit of logging in Couchbase Lite that can be enabled for troubleshooting purposes. Serious/unexpected problems will always be logged with a message starting "WARNING:", but less serious logs need to be enabled using user-defaults or command-line arguments.

The Logging API

Couchbase Lite uses the logging API from the MYUtilities library. There's a Log(@"...") function that's used just like NSLog. It produces no output by default, but there's a master switch to turn it on (the boolean user default also called Log.)

Beyond that, the LogTo(Channel, @"...") function will log to an arbitrary named "channel". Channels are off by default but are individually enabled by user defaults, so for instance the default LogFoo turns on the Foo channel. (But only if the master log switch is enabled too.)

Enabling Logging

You can turn these flags on programmatically with the NSUserDefaults class, or persistently from the command-line using the defaults tool (using your app's bundle ID, of course), but during development the most convenient way is to set them from Xcode's scheme editor. This lets you toggle them with GUI checkboxes. Here's how:

  1. Pull down the scheme menu in the toolbar and choose "Edit Scheme..."
  2. Choose "Run" from the source list on the left side of the sheet.
  3. Choose the "Arguments" tab.
  4. Click the "+" button at the bottom of the "Arguments Passed On Launch" list.
  5. In the new list item that appears, type -Log YES.

This adds two command-line arguments when Xcode launches your app. NSUserDefaults parses these at launch time and temporarily sets the value of Log to YES (aka true.) This is persistent as long as you run your app from Xcode, but it's not stored in the system/device user defaults so it has no effect on launching your app normally. Moreover, you can easily turn it off using the checkbox next to its list item.

Enabling "channels" works the same way. Add another argument item whose value is e.g. -LogFoo YES to turn on channel Foo. (Remember that you also need to have the -Log YES item enabled or no logs will appear at all.)

Useful Logging Channels

Most of Couchbase Lite's logging goes to specific channels. Here are some useful ones to turn on:

  • Sync -- High-level status of sync/replication.
  • RemoteRequest -- The individual HTTP requests the replicator sends to the remote server.
  • ChangeTracker -- The pull replicator's _changes feed listener.
  • View -- View indexing.
  • Query -- View queries.
  • Router -- If using the REST API, this logs info about the URL requests being handled. (NOTE: Was CBLRouter prior to 1.3)
  • Database -- CRUD operations, etc. (NOTE: Was CBLDatabase prior to 1.3)
  • Upgrade -- Logged during the process of upgrading a database upon open (e.g. from SQLite to ForestDB.)

NOTE: You can append Verbose to the name of a channel to enable more verbose messages, e.g. SyncVerbose.

Clone this wiki locally