ajsharp/bunyan

Make logging useful (and easy!) with Bunyan and MongoDB.

Bunyan

Bunyan is a thin ruby wrapper around a MongoDB capped collection, created with high-performance, flexible logging in mind.

Bunyan is not intended to be used as a drop-in replacement for the default rails logger. If you need to do this, please see peburrows' mongo_db_logger.

However, there is planned support for a flexible middleware component to drop in to your rails app.

Install

gem install bunyan

Configure

The only configuration options required are the database and collection name.

For rails apps, put the following config block in an initializer.

# config/initializers/bunyan.rb
Bunyan::Logger.configure do
  # required options
  database   'bunyan_logger'
  collection 'development_log'

  # optional
  host     'some.remote.host' # defaults to localhost
  port     '12345'            # defaults to 27017
  disabled true

  # other connection option
  # Specify a valid ruby driver connection object (single / pair)
  # if you do so, host / port are ignored 
  connection = $connection
end

# Gemfile
gem 'bson_ext', '1.1' # set the version to whatever the current version of bson the mongo gem is using

Usage

You can access the bunyan logger anywhere is your app via Bunyan::Logger. The Logger class is implemented as a singleton, and you can call any instance method on the Logger class. This is implemented with some method_missing magic, which is explained in a bit more detail below.

Middleware

To make use of Bunyan in your web apps, you need some way to capture request data. I have added an example middleware (which is extremely, extremely ugly) which you can find at examples/middleware.rb.

There are plans for a standard middleware API, but it has not yet been implemented. If you have interest in helping/collaborating on this feature, please get in touch with me.

Until the middleware API is complete, please use this example middleware at your own risk!

Internals

Bunyan makes heavy usage of method_missing both at the class and instance level. At the class level, this is purely for convenience to pass missing class methods to the singleton instance, which precludes us from needing to use Logger.instance directly. At the instance level, method_missing is used to provide a very thin layer around MongoDB, via the Mongo driver.

The net effect of this is that there is no reason to muck around with calling methods directly on Bunyan::Logger.instance, because all methods that don't already exist at the class level will be sent to Bunyan::Logger.instance.

Bunyan::Logger.count == Bunyan::Logger.instance.count # => true

Also, you can call any instance methods Bunyan::Logger that you would otherwise call on a Mongo collection object.

More

• MongoDB Capped Collections
• Mongo Ruby Driver

TODO

• Ability to specify auth creds for making a mongo connection
• Fail silently if no mongo server running
• Ability to limit bunyan to only run in certain environments
• Add middleware client for easy drop-in to rails/rack apps
• Add ability to connect to a remote mongo server
• Ability to configure size of capped collection

bunyan's Issues

Bunyan should be able to connect to a remote Mongo server