Repository is archived
No commit activity in last 3 years
No release in over 3 years
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.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.11
~> 10.0
~> 3.0

Runtime

 Project Readme

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).

©2016 Deseret Book and contributors. Developed by Mike Bourgeous at DeseretBook.com, with metadata work by Dustin Grange. See Git for any additional contributors.