Class: Lug::Logger

Inherits:
Object
  • Object
show all
Includes:
Standard::LoggerDeviceMethods, Standard::LoggerMethods
Defined in:
lib/lug/logger.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Standard::LoggerDeviceMethods

#debug, #error, #fatal, #info, #unknown, #warn

Constructor Details

#initialize(dev_or_io = nil, namespace = nil) ⇒ Logger

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.

Parameters:

  • dev_or_io (Lug::Device, IO) (defaults to: nil) —

    device or IO instance

  • namespace (String, Symbol) (defaults to: nil) 


69
70
71
72
73
74
 
# 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

Instance Attribute Details

#device ⇒ Object (readonly)

Returns the value of attribute device.



58
59
60
 
# File 'lib/lug/logger.rb', line 58

def device
  @device
end

#namespace ⇒ Object (readonly)

Returns the value of attribute namespace.



58
59
60
 
# File 'lib/lug/logger.rb', line 58

def namespace
  @namespace
end

Instance Method Details

#enabled? ⇒ Boolean

Return true if logger is enabled for current namespace

When false, #log won’t write anything to its device

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/lug/logger.rb', line 104

def enabled?
  @enabled
end

#log(message = nil) ⇒ NilClass Also known as: <<

Log a message to output device

Parameters:

  • message (String) (defaults to: nil)

Returns:

  • (NilClass) 


81
82
83
84
85
 
# File 'lib/lug/logger.rb', line 81

def log(message = nil)
  return unless @enabled
  message ||= yield if block_given?
  @device.log(message, @namespace)
end

#on(namespace) ⇒ Lug::Logger

Clone logger with the same device and namespace

Parameters:

  • namespace (String, Symbol)

Returns:



93
94
95
96
 
# File 'lib/lug/logger.rb', line 93

def on(namespace)
  namespace = [@namespace, namespace].compact.join(':'.freeze)
  Logger.new(@device, namespace)
end