Some time ago, I started looking at CouchDB. Getting to know technologies is IMO always best performed by thinking up some kind of project. So first, I started thinking of what to do with it. Now that the 1.0.0 has been released I thought it would be good to (finally) blog about my findings so far.

The project I came up with is the following: A simple (OSGi) log listener that stores its log messages into a CouchDB database.

At Luminis we use OSGi a lot. It is a highly modular framework (written in Java) that allows you to combine several modules (called ‘bundles’) that each expose or make use of functionality provided by other bundles. Careful combination of several bundles will result (almost like ‘emerging behavior’) in a complete application that suits your needs. The functionality provided by a particular bundle is best exposed through interfaces, enabling you to switch implementations without breaking the contract with other bundles that use the exposed functionality.

One of the compendium services that are available is the LogService. It allows any service to log the things it considers of any importance. It is then up to the LogService implementation where these log statements end up. Logging is usually sent to standard out or a file, which is fine in most cases. Sometimes however, logging onto the device itself and retrieving the log file for inspection is not an easy task. Take for example an Android device. Thanks to Aaron Miller’s effort, we are now able to run CouchDB on Android. Android apps (EZDroid apps) will now be able to store their logging data in this local instance. This data can then be easily replicated to another instance for inspection.

Also,  for limited devices (where there’s e.g. limited storage available) logging to a file is simply not an option.

Therefore I thought of the following scenarios where

• CouchDB is installed locally on the device/ server. Access to CouchDB is then guaranteed and no logging is missed. A drawback might be that the OSGi application would require a local installation of CouchDB (for those who consider that a drawback!).

• CouchDB is installed on a remote instance. Access to the CouchDB instance might be interrupted due to network instability. Then, some log messages might get lost. Since most applications require a working internet connection,  I think we could live with this.

The target of the project would be to store a JSON representation of the actually logged messages into CouchDB. This can easily be accomplished by using a LogListener.

In both cases, the OSGi LogListener that ‘lives’ inside the OSGi application, receives all LogEntries, that contain the messages that are being sent to the LogService (and some meta-data). All it then has to do is convert it to JSON and create a new document in some database at the CouchDB server. If one ever wanted to inspect the log messages, a single call to the CouchDB server would initiate a replication of the database to your local CouchDB instance. Then, you could peruse the log messages offline at your leisure.

Installation and the basic usage of CouchDB is not covered here, there are excellent descriptions already available on the Wiki, Halorgium’s GitHub and the O’Reilly Free Book.

To test the setup described above, I created such a LogListener implementation. I use json-simple to convert the LogEntry into JSON and end up with a JSON Object such as the following:

{
'message': 'This is a test message',
'time': 1269783246909,
'level': 'LOG_DEBUG',
'serviceReference': {},
'bundle': {
   'id': 5,
    'lastModified': 1269783246510,
    'location': 'file:bundle/net.luminis.log.couchdb-1.0.0.jar',
    'symbolicName': 'net.luminis.log.couchdb'
    }
}

A unique serverId/ instanceId could also be added to be able to distinguish between server instances if you decide to send the logging to a central server.

This, I POST to the configured server. By not submitting an ‘_id’ in the JSON string, CouchDB will make one up for me. The HTTP (1.0) POST itself is done (thus keeping it lightweight) opening a raw socket to the couchdb server:

POST /db HTTP/1.0
Content-Length: xxx
Content-Type: application/json

{ ... the data here ... }

The response is also a valid JSON response which can be inspected for success (along with the HTTP response code, of course).

In my current implementation, I can choose between two modes; either each message is sent to the couchdb instance on at a time, or I send all messages in bulk mode every x seconds. The latter is probably the best for remote couchdb instances.