module LogJam

Constants

LEVEL_MAP: Module constants.
STREAM_MAP
VERSION

Public Class Methods

apply(target, name=nil, context={}) click to toggle source

This method is used to install logging facilities at the class level for a given class. Once 'logified' a class will possess two new methods. The first, log(), retrieves the logger associated with the class. The second, log=(), allows the assignment of the logger associated with the class. Note that changing the logger associated with a class will impact all other classes that use the same logger.

Parameters¶ ↑

target: The target class that is to be extended.
name: The name of the logger to be used by the class. Defaults to nil to indicate use of the default logger.
context: A Hash of additional parameters that are specific to the class to which LogJam is being applied.

# File lib/logjam.rb, line 56
def self.apply(target, name=nil, context={})
  @@logjam_contexts[target] = {}.merge(context)
  target.extend(LogJam.get_module(name, @@logjam_contexts[target]))
  target.send(:define_method, :log) {LogJam.get_logger(name)} if !target.method_defined?(:log)
end

configure(source=nil) click to toggle source

This method is used to configure the LogJam module with the various loggers it will use.

Parameters¶ ↑

source: Either a Hash containing the configuration to be used or nil to indicate the use of default configuration settings.

# File lib/logjam.rb, line 37
def self.configure(source=nil)
  @@logjam_modules = {}
  @@logjam_loggers = {}
  LogJam.process_configuration(source ? source : Configuration.instance)
end

get_logger(name=nil) click to toggle source

This method attempts to fetch the logger for a specified name. If this logger does not exist then a default logger will be returned instead.

Parameters¶ ↑

name: The name of the logger to retrieve.

# File lib/logjam.rb, line 67
def self.get_logger(name=nil)
  LogJam.process_configuration(Configuration.instance) if @@logjam_loggers.empty?
  @@logjam_loggers.fetch(name, @@logjam_loggers[nil])
end

names() click to toggle source

This method fetches a list of the names currently defined within the LogJam internal settings.

# File lib/logjam.rb, line 74
def self.names
  @@logjam_loggers.keys.compact
end

Private Class Methods

create_logger(definition) click to toggle source

This method creates a logger from a given definition. A definition should be a Hash containing the values that are used to configure the Logger with.

Parameters¶ ↑

definition: A Hash containing the configuration details for the logger.

# File lib/logjam.rb, line 154
def self.create_logger(definition)
  # Fetch the configuration values.
  definition = to_definition(definition)
  rotation   = definition.rotation
  max_size   = definition.max_size
  device     = STREAM_MAP.fetch(definition.file.downcase.strip, definition.file)

  if rotation.kind_of?(String) && /^\s*\d+\s*$/ =~ rotation
    rotation = rotation.to_i
    rotation = 0 if rotation < 0
  end

  max_size = max_size.to_i if !max_size.nil? && max_size.kind_of?(String)
  max_size = 1048576 if !max_size.nil? && max_size < 1024

  # Create the actual logger and associated module.
  logger                 = LogJam::Logger.new(device, rotation, max_size)
  logger.level           = LEVEL_MAP.fetch(definition.level.downcase.strip, Logger::DEBUG)
  logger.name            = definition.name
  logger.progname        = definition.name
  @@logjam_loggers[definition.name] = logger
  logger_module          = LogJam.create_module(name)
  if definition.default
    @@logjam_loggers[nil]  = logger
    @@logjam_modules[nil]  = logger_module
  end
  logger
end

create_module(name) click to toggle source

This method is used to create an anonymous module under a given name (if it doesn't already exist) and return it to the caller.

Parameters¶ ↑

name: The name to create the module under.

# File lib/logjam.rb, line 135
def self.create_module(name)
  if !@@logjam_modules.include?(name)
    # Create the anonymous module and add methods to it.
    @@logjam_modules[name] = Module.new
    @@logjam_modules[name].send(:define_method, :log) do
       LogJam.get_logger(name)
    end
    @@logjam_modules[name].send(:define_method, :log=) do |logger|
       LogJam.get_logger(name).logger = logger
    end
  end
  @@logjam_modules[name]
end

get_module(name, context={}) click to toggle source

This method fetches the module associated with a name. If the module does not exist the default module is returned instead.

Parameters¶ ↑

name: The name associated with the module to return.
context: The context that applies to the module to be retrieved.

# File lib/logjam.rb, line 92
def self.get_module(name, context={})
  LogJam.create_module(name)
end

process_configuration(settings) click to toggle source

This method processes a logger configuration and generates the appropriate set of loggers and internal objects from it.

Parameters¶ ↑

settings: A collection of the settings to be processed.

# File lib/logjam.rb, line 101
def self.process_configuration(settings)
  settings = Configurative::SettingsParser.new.parse(settings) if settings.kind_of?(Hash)
  if settings && !settings.empty?
    loggers = settings.loggers
    if loggers
       if loggers.kind_of?(Array)
          loggers.each {|definition| LogJam.create_logger(definition)}
       elsif loggers.kind_of?(Hash)
          LogJam.create_logger(loggers)
       else
          raise Error, "The loggers configuration entry is in an "\
                       "unrecognised format. Must be either a Hash or an "\
                       "Array."
       end
    end

    aliases = settings.aliases
    if aliases
       aliases.each do |name, equivalent|
          @@logjam_loggers[name] = @@logjam_loggers[equivalent]
          @@logjam_modules[name] = LogJam.get_module(equivalent)
       end
    end
  end

  # Create a default logger if one hasn't been specified.
  LogJam.create_logger({default: true, file: "STDOUT"}) if @@logjam_loggers[nil].nil?
end

to_definition(settings) click to toggle source

# File lib/logjam.rb, line 183
def self.to_definition(settings)
  settings = Configurative::SettingsParser.new.parse(settings) if settings.kind_of?(Hash)
  settings.file  = "stdout" if !settings.include?(:file) || settings.file == ""
  settings.level = "debug" if !settings.include?(:level) || settings.level == ""
  settings
end

Public Instance Methods

log() click to toggle source

A convenience mechanism that provides an instance level access to the class level logger.

# File lib/logjam.rb, line 80
def log
  self.class.log
end