Awesome

StructuredLogger

A structured logger with Ruby's Logger interface.

Installation

General Ruby application

Add this line to your application's Gemfile:

gem 'structured_logger'

And then execute:

$ bundle

Or install it yourself as:

$ gem install structured_logger

Rails application

Add to Gemfile (see previous section) and run bundle.

Write config/initializers/structured_logger.rb.

# Use StructuredLogger instead of Logger.
l = StructuredLogger.new("log/#{Rails.env}.log")

# If you want timestamp and PID with ActiveSupport::TaggedLogging, enable next line.
#l.formatter = ::Logger::Formatter.new

# If you want tagging support, enable next line.
#l = ActiveSupport::TaggedLogging.new(l)

Rails.logger = l

Play it!

Usage

We can write log with parameters.

t = Time.now; sleep(0.1)
l = StructuredLogger.new(STDOUT)

l.debug("processed request", started_at: t, elapsed_sec: Time.now - t, status: "ok")
#=> D, [2015-08-21T05:14:37.022621 #8310] DEBUG -- : processed request: started_at=2015-08-21 05:14:36 +0900 elapsed_sec=0.100156444 status="ok"

l.debug { ["processed request", started_at: t, elapsed_sec: Time.now - t, status: "ok"] }
#=> D, [2015-08-21T05:15:00.214480 #8416] DEBUG -- : processed request: started_at=2015-08-21 05:15:00 +0900 elapsed_sec=0.100193648 status="ok"

StructuredLogger instance methods have Ruby's Logger interface. So, we can replace Ruby's Logger to StructuredLogger.

l = Logger.new(STDOUT)
l.error("Something happend")
#=> E, [2015-08-25T06:43:18.244950 #23623] ERROR -- : Something happend

l = StructuredLogger.new(STDOUT)
l.error("Something happend")
#=> E, [2015-08-25T06:43:47.798889 #23623] ERROR -- : Something happend

Also we can use it with ActiveSupport::TaggedLogging.

l = ActiveSupport::TaggedLogging.new(StructuredLogger.new(STDOUT))
l.tagged(:crawler) do
  l.tagged(:downloading) do
    l.warn("malformed file format", path: downloaded_path.to_s)
  end
end
#=> [crawler] [downloading] malformed file format: path="/opt/app/tmp/1234.bin"

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake false to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/nishidayuya/structured_logger.