Ruby logging library that provides the ability to add class/module specific filters

View the Project on GitHub gshutler/hatchet


Build status

Hosted on GitHub Pages — Theme by orderedlist

Rails Installation

Hatchet includes a Railtie that is loaded automatically and wraps the Rails.logger.

Add this line to your application’s Gemfile to get Hatchet from RubyGems.org:

gem 'hatchet'

And then execute:

$ bundle

To make it so your log calls are scoped to your controllers you also need to add Hatchet to your ApplicationController:

class ApplicationController < ActionController::Base
  include Hatchet

You could include it in your models so that each of those has its own logging context too.


By default the Railtie will wrap the standard Rails logger. If you want to utilize some of the more advanced functionality of Hatchet it is recommended that you place your configuration into config/initializers/hatchet.rb.

Before specifying your custom configuration you may want to reset Hatchet in order to remove the Rails logger from its configuration:

Hatchet.configure do |config|
  # Remove any existing configuration
  # Then specify your custom configuration

You can also specify configuration in the standard config/application.rb and the corresponding environment-specific configuration files (such as config/environments/production.rb).

The Hatchet configuration is available through config.hatchet. If you are setting just one property you can access it directly:

config.hatchet.level :error

However, if you want to specify multiple values it will read better if you use the block form:

config.hatchet.configure do |hatchet|
  hatchet.level :error
  hatchet.formatter = SimpleFormatter.new
  hatchet.appenders << CustomAppender.new


There are some special considerations when using Hatchet with Heroku. Heroku doesn’t have a file system so adds the rails_log_stdout plugin for you. However, rails_log_stdout monkey patches the Rails logger meaning Hatchet cannot hook into it as it can in normal environments.

“I don’t care about the backstory, how do I get Hatchet to work with Heroku?” I’m glad you asked.

Stop Heroku installing rails_log_stdout

At the terminal within your application’s root directory:

$ mkdir -p vendor/plugins/rails_log_stdout
$ touch vendor/plugins/rails_log_stdout/.gitkeep
$ git commit -am "Prevent Heroku adding rails_log_stdout"

This stops the Heroku application packaging process from adding the rails_log_stdout plugin on your behalf.

Configure Hatchet to log to STDOUT

Add the following configuration to your config/environments/production.rb:

config.hatchet.configure do |hatchet|
  # Reset the logging configuration
  # Use the format without time, etc so we don't duplicate it
  hatchet.formatter = Hatchet::SimpleFormatter.new
  # Set up a STDOUT appender
  hatchet.appenders << Hatchet::LoggerAppender.new do |appender|
    appender.logger = Logger.new(STDOUT)

This removes any previous configuration (such as the default Rails logger that will to write to a file) and then adds an appender writing to STDOUT. The use of the SimpleFormatter is just a suggestion, you are of course free to use any formatter you want.

Make STDOUT write synchronously

Usually STDOUT batches lines together when writing as it writes them out asynchronously. This can be a bit rubbish with logs so you need to force it to write synchronously. I usually put this into my config.ru:

STDOUT.sync = true