Lumber

Lumber tries to make it easy to use the more robust log4r logging system within your rails application. To do this it sets up log4r configuration from a yml file, and provides utility methods for adding a :logger accessor to classes dynamically as they get created. In the default setup shown below, calls to logger from a model/controller/mailer, will include that classes name in the log output.

To use it in a rails project:

• add lumber to your Gemfile
• bundle install
• run the lumber generator, rails generate lumber, to get a basic config/log4r.yml

• enable lumber in your config/application.rb:

  To expose custom variables in log4r.yml

  config.lumber.some_option = "some_value

  you can set default_log_level here, config/environments/*.rb or in config/log4r.yml

  config.log_level = :debug

  enabling lumber sets config.logger to Log4r::Logger['rails']

  config.lumber.enabled = true

You should be able to use lumber in a non-rails project too, but you will have to manually call Lumber.init - see the docs for details on parameters:

# before Rails::Initializer.run
#
require 'lumber'
Lumber.init(:root => "/my/project", :env => "development")

# Setup parent loggers for some known rails Base classes.  Classes that inherit
# from these will have their logger as a parent so you can configure logging for
# subtrees of classes in log4r.yml
Lumber.setup_logger_hierarchy("ActiveRecord::Base", "rails::models")
Lumber.setup_logger_hierarchy("ActionController::Base", "rails::controllers")
Lumber.setup_logger_hierarchy("ActionMailer::Base", "rails::mailers")

# If you really want, you can make all classes have a logger
# Lumber.setup_logger_hierarchy("Object", "root::object")

Additionally, you can also add loggers to individual classes by including the LumberLoggerSupport module

class Foo
  include Lumber::LoggerSupport
end

and Foo.logger/Foo.new.logger will log to a logger named "rails::Foo". This creates a heirarchy of loggers for classes nested within modules, so you can use the namespace to enable/disable loggers

If you want to change the log level for a different environment, you can do so in log4r.yml or by using the standard rails "config.log_level" setting in config/environments/.rb

# Set info as the default log level for production
config.log_level = :info

Lumber also comes with a Sinatra UI for dynamically overriding log levels at runtime. To use it, just run Lumber::Server as a rack application. The easiest way to do this is to map it to a route in your rails routes.rb (make sure you password protect it):

require 'lumber/server'
mount Lumber::Server, :at => "/lumber"

This will allow you to temporarily set lower log levels for specific loggers - e.g. if you want a specific model to have DEBUG logging for the next hour.

Copyright

Copyright (c) 2009-2012 Matt Conway. See LICENSE for details.