class Lug::Logger

Logger class provides a small logging utility for debugging libraries and applications in Ruby.

Usually meassages are grouped hierarchically in namespaces, so that different parts of your source code can be logged separately from each other, when needed.

By convention, namespaces are lowercase strings separated by a colon ':' to denote a nested namespace. Regardless, any string formatting can be used.

A Logger is associated with a Device, which manages an IO instance. Lug detects if IO referes to a TTY (Teletype terminal), and uses ANSI colors to format log messages by default. Otherwise, it will use a proper format for log files.

logger = Lug::Logger.new
logger << 'hi there!'

main_logger = logger.on(:main)
main_logger << 'now logging from the "main" namespace'

Because Lug is intented to be used to debug both libraries and applications, Lug doesn't print anything unless you correctly set the DEBUG environment variable. This variable indicates which namespaces you want to log when you run your Ruby script.

For example, if your script is:

require 'lug'

logger = Lug::Logger.new
logger.on(:foo) << 'Message from foo'
logger.on(:bar) << 'Message from bar'
logger.on(:baz) << 'Message from baz'

Then, running with `DEBUG=foo,bar` will print

foo Message from foo +0ms
bar Message form bar +0ms

You can also use wildcars to filter in all messages form a specific namespace and all its nested namespaces.

DEBUG=worker:* ruby process.rb

worker:a I am worker A +0ms
worker:b I am worker B +1ms
worker:b Doing something... +0ms
worker:a Doing something... +2ms
worker:a Done! +963ms
worker:b Done! +2s

Attributes

device[R]
namespace[R]

Public Class Methods

new(dev_or_io = nil, namespace = nil) click to toggle source

Create a Logger for device within namespace

When dev_or_io is an IO instance, a Device or TtyDevice will be created with it, depending on IO#isatty. That is, if IO instance refers to a TTY output, it will use a TtyDevice.

@param dev_or_io [Lug::Device, IO] device or IO instance @param namespace [String, Symbol]

# File lib/lug/logger.rb, line 69
def initialize(dev_or_io = nil, namespace = nil)
  dev_or_io ||= STDERR
  @device = dev_or_io.is_a?(Device) ? dev_or_io : Helpers.device_from(dev_or_io)
  @namespace = namespace && namespace.to_s
  @enabled = @device.enabled_for?(@namespace)
end

Public Instance Methods

<<(message = nil)
Alias for: log
enabled?() click to toggle source

Return true if logger is enabled for current namespace

When false, log won't write anything to its device

@return [Boolean]

# File lib/lug/logger.rb, line 104
def enabled?
  @enabled
end
log(message = nil) { || ... } click to toggle source

Log a message to output device

@param message [String] @return [NilClass]

# File lib/lug/logger.rb, line 81
def log(message = nil)
  return unless @enabled
  message ||= yield if block_given?
  @device.log(message, @namespace)
end
Also aliased as: <<
on(namespace) click to toggle source

Clone logger with the same device and namespace

@param namespace [String, Symbol] @return [Lug::Logger]

# File lib/lug/logger.rb, line 93
def on(namespace)
  namespace = [@namespace, namespace].compact.join(':'.freeze)
  Logger.new(@device, namespace)
end