What is Hatchet?

Hatchet is a logging framework written from the ground up in Ruby. It has been inspired by the likes of log4j and slf4j but is not a port of either of them.

Hatchet aims to integrate seamlessly with your Ruby projects and provide a single logging interface that can pass on messages to any backend you want to use.

Read more about Hatchet

Installation

Hatchet has specific hooks for Rails and Sinatra though it is suitable for use in any Ruby project. Please select the installation guide that most suits your scenario below:

• Install for Rails
• Install for Sinatra
• Standard Ruby install

Usage

To use the logger you must add it to your classes as a mixin or use it to extend your modules. Then you can call the logger through the methods log and logger. They are aliases for the same method to ease migration.

Classes

class Foo
  include Hatchet

  def self.class_work
    log.info { 'Doing some class work' }
  end

  def work
    log.info { 'Doing some instance work' }
  end

  def dangerous_work
    log.info { 'Attempting dangerous work' }
    attempt_dangerous_work
    log.info { 'Dangerous work complete' }
    true
  rescue => e
    log.error "Dangerous work failed - #{e.message}", e
    false
  end
end

Modules

module Bar
  include Hatchet

  def self.work
    log.info { 'Doing some module work' }
  end

  def work
    log.info { 'Doing some mixin work' }
  end
end

Logging API

The logger has all the core methods you are used to from the standard logger for logging messages taking either a String or a lazily-evaluated block:

• debug
• info
• warn
• error
• fatal

It is recommended you use the block version as it avoids needless string interpolation when possible. However, if you are providing an error it reads better to use the String version, passing the error as a second parameter:

log.debug { "Not #{evaluated} unless debug messages enabled" }
log.debug "Whereas this is always #{evaluated}"

log.error "Something bad happened - #{error.message}", error

An error can be passed to any level logging call.

It also has all the methods for checking whether logging is active at a given level:

• debug?
• info?
• warn?
• error?
• fatal?

The level of logging can be controlled down to the class level and each message can be logged to several locations. See the configuration guide for more details.

Contributing

1. Fork it on GitHub
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

All pull requests should come complete with tests when appropriate and should follow the existing style which is best described in Github’s Ruby style guide. Bonus internet points are provided if you submit a pull request for the gh-pages branch too.