Logbert¶ ↑

Just your friendly, neighborhood logger!

Why another logger?¶ ↑

Traditional Ruby loggers make it difficult to change your logging behaviors without also modifying your application’s code. For example:

require 'logger'

# This does not belong here.  Why does my application
# care that the messages will be streamed to $stdout ?
LOG = Logger.new $stderr

# This does not belong here.  Why does my application
# care that messages will only be recorded when they
# are at WARN level or higher?
LOG.level = Logger::WARN

# This is all that my application should care about.
LOG.warn "Umm... something weird happened..."

Logbert aims to establish a clear separation between “what” is logged versus “how” it is logged. Thus, the application only needs to focus on “what” to log. Decisions about “how” to filter log messages and “how” to persist them can be specified from outside of the application.

Usage¶ ↑

Creating Loggers¶ ↑

Logbert always defines a root logger for you. So, the easiest way to begin using Logbert is to just latch on to this logger:

require 'logbert'
LOG = Logbert.root

However, if you’d like to take advantage of the logging hierarchy, then you can create a separate Logger for each class / module in your code. For instance:

require 'logbert'

class MyClass
  LOG = Logbert[self]

end

If you don’t want your Logger hierarchy to mimic your class / module hierarchy, then you can just specify your own hierarchy instead:

require 'logbert'

class MyOtherClass
   LOG = Logbert["foo/bar"]
end

Once a Logger has been created, it will persist for the lifetime of the application. For instance:

require 'logbert'

if Logbert["foo"] === Logbert["foo"]
  puts "It's the same Logger instance!"
end

if Logbert["foo"] === Logbert["foo/bar"]
  puts "This message will never be printed"
end

Configuring Output Handlers¶ ↑

So far, none of the Loggers that we have created will actually log anything because we have not configured any output handlers. Let’s fix that:

require 'logbert'

Logbert["foo"].handlers << Logbert::Handlers::StreamHandler.new($stderr)

Now the “foo” Logger and will write all of its messages to $stderr. Note, however, that we have still not defined any handlers for the root logger. This means that messages sent to the root logger will not be recorded anywhere:

Logbert["foo"].warn "This will get recorded"
Logbert.root.warn   "This will NOT get recorded"

By default, Loggers also inform their parents of any log messages that they receive. Therefore:

Logbert["foo/bar"].warn "This will get recorded by Logbert['foo']'s handlers"

Writing log files¶ ↑

At some point, you probably want to write your log output to the filesystem. Here’s how you can do that.

Logbert["foo"].handlers << Logbert::Handlers::StreamHandler.for_path("log/application.log")