module Swiftcore::Analogger::Client::LoggerInterface

Description

LoggerInterface provides a module which may be used to extend an Analogger Client interface, and provide a dual-mode interface, supporting both the analogger client api, and the logger api.

Description From logger.rb:

The Logger class provides a simple but sophisticated logging utility that anyone can use because it's included in the Ruby 1.8.x standard library.

The HOWTOs below give a code-based overview of Logger's usage, but the basic concept is as follows. You create a Logger object (output to a file or elsewhere), and use it to log messages. The messages will have varying levels (info, error, etc), reflecting their varying importance. The levels, and their meanings, are:

FATAL

an unhandleable error that results in a program crash

ERROR

a handleable error condition

WARN

a warning

INFO

generic (useful) information about system operation

DEBUG

low-level information for developers

So each message has a level, and the Logger itself has a level, which acts as a filter, so you can control the amount of information emitted from the logger without having to remove actual messages.

For instance, in a production system, you may have your logger(s) set to INFO (or WARN if you don't want the log files growing large with repetitive information). When you are developing it, though, you probably want to know about the program's internal state, and would set them to DEBUG.

Example

A simple example demonstrates the above explanation:

log = Swiftcore::Analogger::Client.new('logger_interface','127.0.0.1','47990')
log.extend(Swiftcore::Analogger::Client::LoggerInterface) 
log.level = Logger::WARN

log.debug("Created logger")
log.info("Program started")
log.warn("Nothing to do!")

begin
  File.each_line(path) do |line|
    unless line =~ /^(\w+) = (.*)$/
      log.error("Line in wrong format: #{line}")
    end
  end
rescue => err
  log.fatal("Caught exception; exiting")
  log.fatal(err)
end

Because the Logger's level is set to WARN, only the warning, error, and fatal messages are recorded. The debug and info messages are silently discarded.

How to log a message

Notice the different methods (fatal, error, info) being used to log messages of various levels. Other methods in this family are warn and debug. add is used below to log a message of an arbitrary (perhaps dynamic) level.

  1. Message in block.

    logger.fatal { "Argument 'foo' not given." }
    
  2. Message as a string.

    logger.error "Argument #{ @foo } mismatch."
    
  3. With progname.

    logger.info('initialize') { "Initializing..." }
    
  4. With severity.

    logger.add(Logger::FATAL) { 'Fatal error!' }
    

Setting severity threshold

  1. Original interface.

    logger.sev_threshold = Logger::WARN
    
  2. Log4r (somewhat) compatible interface.

    logger.level = Logger::INFO
    
    DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
    

Constants

LevelToSeverity
MapUnknownTo
SeverityToLevel

A severity is the worded name for a log level A level is the numerical value given to a severity

Attributes

level[RW]

Logging severity threshold (e.g. Logger::INFO).

sev_threshold[RW]

Logging severity threshold (e.g. Logger::INFO).

sev_threshold=[RW]

Logging severity threshold (e.g. Logger::INFO).

Public Class Methods

extend_object(log_client) click to toggle source
# File lib/swiftcore/LoggerInterface.rb, line 140
def self.extend_object(log_client)

  class <<log_client
    include ::Swiftcore::Analogger::Client::LoggerInterface
    alias analog log
    
    # The interface supports string names, symbol names and levels as the first
    # argument. It therefrore covers both the standard analogger api, and the
    # logger api, and some other string based log level api.
    # N.B. This adds one main limitation - all levels are commonly downcased
    # by this interface.
    def add(severity, message = nil, progname = nil, &block)
      level = severity
                    
      case severity
      when Numeric
        severity = LevelToSeverity[level]
      when Symbol
        severity = severity.to_s.downcase
        level = SeverityToLevel[severity]
      when String
        severity = severity.to_s.downcase
        level = SeverityToLevel[severity]
      else
        raise ArgumentError.new('#add accepts either Numeric, Symbol or String')
      end
      return true unless @level <= level
      
      # We map severity unknown to info by default. MapUnknownTo.replace('mylevel')
      # to change that.
      severity = MapUnknownTo if severity == 'unknown'

      progname ||= @service
      if message.nil?
        if block_given?
          message = yield
        else
          message = progname
          progname = @service
        end
      end

      analog( severity, message )
      true
    end
    alias log add
    
  end
  
  # Default log level for logger is 0, maybe a good idea to fetch from logger itself.
  log_client.level ||= 0
  log_client
end

Public Instance Methods

<<(raw) click to toggle source

As there is no notion of a raw message for an analogger client, this sends messages at the default log level (unknown, which is mapped to MapUnknownTo).

# File lib/swiftcore/LoggerInterface.rb, line 196
def <<(raw)
  add(nil, raw)
end
debug(message = nil, &block) click to toggle source

Log a DEBUG message.

See info for more information.

# File lib/swiftcore/LoggerInterface.rb, line 247
def debug(message = nil, &block)
  add(DEBUG, message, nil, &block)
end
debug?() click to toggle source

Returns true iff the current severity level allows for the printing of DEBUG messages.

# File lib/swiftcore/LoggerInterface.rb, line 224
def debug?; @level <= DEBUG; end
error(message = nil, &block) click to toggle source

Log an ERROR message.

See info for more information.

# File lib/swiftcore/LoggerInterface.rb, line 291
def error(message = nil, &block)
  add(ERROR, message, nil, &block)
end
error?() click to toggle source

Returns true iff the current severity level allows for the printing of ERROR messages.

# File lib/swiftcore/LoggerInterface.rb, line 236
def error?; @level <= ERROR; end
fatal(message = nil, &block) click to toggle source

Log a FATAL message.

See info for more information.

# File lib/swiftcore/LoggerInterface.rb, line 300
def fatal(message = nil, &block)
  add(FATAL, message, nil, &block)
end
fatal?() click to toggle source

Returns true iff the current severity level allows for the printing of FATAL messages.

# File lib/swiftcore/LoggerInterface.rb, line 240
def fatal?; @level <= FATAL; end
info(message = nil, &block) click to toggle source

Log an INFO message.

The message can come either from the progname argument or the block. If both are provided, then the block is used as the message, and progname is used as the program name.

Examples

logger.info("MainApp") { "Received connection from #{ip}" }
# ...
logger.info "Waiting for input from user"
# ...
logger.info { "User typed #{input}" }

You'll probably stick to the second form above, unless you want to provide a program name (which you can do with Logger#progname= as well).

Return

See add.

# File lib/swiftcore/LoggerInterface.rb, line 273
def info(message = nil, &block)
  add(INFO, message, nil, &block)
end
info?() click to toggle source

Returns true iff the current severity level allows for the printing of INFO messages.

# File lib/swiftcore/LoggerInterface.rb, line 228
def info?; @level <= INFO; end
progname() click to toggle source
# File lib/swiftcore/LoggerInterface.rb, line 204
def progname
  @service
end
progname=(name) click to toggle source
# File lib/swiftcore/LoggerInterface.rb, line 200
def progname=(name)
  @service = name
end
unknown(message = nil, &block) click to toggle source

Log an UNKNOWN message. This will be printed no matter what the logger level.

See info for more information.

# File lib/swiftcore/LoggerInterface.rb, line 310
def unknown(message = nil, &block)
  add(UNKNOWN, message, nil, &block)
end
warn(message = nil, &block) click to toggle source

Log a WARN message.

See info for more information.

# File lib/swiftcore/LoggerInterface.rb, line 282
def warn(message = nil, &block)
  add(WARN, message, nil, &block)
end
warn?() click to toggle source

Returns true iff the current severity level allows for the printing of WARN messages.

# File lib/swiftcore/LoggerInterface.rb, line 232
def warn?; @level <= WARN; end