Skip to content

Logging

Jump to bottom
pulkitsinghal edited this page Jun 23, 2012 · 10 revisions

There's a fair bit of logging in TouchDB 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

TouchDB uses the logging API from my 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 TouchDB's logging goes to specific channels. Here are some useful ones to turn on:

  • TDRouter -- Logs info about the 'touchdb:' URL requests being handled, i.e. the REST API your app is calling.
  • Sync -- High-level status of sync/replication.
  • SyncVerbose -- More detailed info about sync/replication.
  • RemoteRequest -- The individual HTTP requests the replicator sends to the remote server.
  • View -- View indexing and queries.
  • ChangeTracker -- The _changes feed listener.

http://www.dropbox.com/s/heclm9gswxg63r5/logging.png

Clone this wiki locally