BlackBox::LogFormatter

This is an incredibly colorful highlighting formatter for structured log events. It is visually similar to Ruby's Logger::Formatter, but can display additional color-highlighted metadata on the same line or on subsequent lines, using ANSI color escape sequences.

Not everyone likes this much color and detail, so you (TODO) can configure which log event fields to display inline, which to display in a multi-line format, and which to hide altogether. You can also disable color.

This gem was extracted from an internal middleware framework at Deseret Book called BlackBox Framework. It's named for the fact that good middleware should allow frontend services to treat backend services like a black box, not caring about implementation details.

Features

Each application name, process, thread, worker, and job gets its own color, so you can visually identify log messages from the same process, thread, or worker in a combined log stream. You need to manually add these metadata fields to your log events if your logger doesn't do it for you.

  threads = []
  10.times do |i|
    threads << Thread.new do
      l.info message: "On thread #{i}", tid: Thread.current.__id__
      sleep rand
      l.info message: "Back on #{i}", tid: Thread.current.__id__
    end
  end ; threads.each(&:join)

Colorized thread IDs

Log events are colored according to severity:
- DEBUG - dark gray
- INFO - default
- WARN - yellow
- ERROR - red
- FATAL - magenta
- UNKNOWN - cyan

  [:debug, :info, :warn, :error, :fatal, :unknown].each do |level|
    l.send(level, { message: "Message at #{level}", a: 1, b: 2, colors: true })
  end

Colorized log levels

Backtraces are colorized to make it easy to identify files, line numbers, and method names:

  l.warn trace: caller

Highlighted backtrace

Installation

Add this line to your application's Gemfile:

gem 'black_box_log_formatter'

Usage

Set BlackBox::LogFormatter as the formatter for a logger, then pass it Hashes instead of Strings. Event Hashes should be simliar to those used by Logstash. Do not pass untrusted data in the message field or as unfiltered fields in the event.

Pass primary metadata fields using symbols as keys, not strings.

require 'black_box_log_formatter'

l = Logger.new($stdout)
l.progname = 'A Program'
l.formatter = BlackBox::LogFormatter.new

l.debug "The old way to log"
# => D, [2016-05-06T16:21:44.520640 #32413] DEBUG -- A Program: hostname The old way to log

l.debug(
  message: "The new way to log",
  tid: 'some thread',
  wid: 'some worker',
  data: { useful: :fields }
)
# => D, [2016-05-06T16:22:32.027060 #32413/T-some thread/W-some worker] DEBUG -- A Program: hostname The new way to log: {
#    :data => {
#      :useful => :fields
#      }
#    }

Simple logging example

TODO: describe configuring the color and formatting options

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/deseretbook/black\_box\_log\_formatter.

License

The gem is available as open source under the terms of the MIT License (see the LICENSE file).