Module: Swiftcore::Analogger::Client::LoggerInterface

Includes:
Logger::Severity
Defined in:
lib/swiftcore/LoggerInterface.rb

Overview

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

Constant Summary collapse

MapUnknownTo = 
'info'
SeverityToLevel =

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

Hash.new
LevelToSeverity = 
Hash.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#level ⇒ Object Also known as: sev_threshold

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



218
219
220
 
# File 'lib/swiftcore/LoggerInterface.rb', line 218

def level
  @level
end

Class Method Details

.extend_object(log_client) ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# 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

Instance Method Details

#<<(raw) ⇒ Object

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).



196
197
198
 
# File 'lib/swiftcore/LoggerInterface.rb', line 196

def <<(raw)
  add(nil, raw)
end

#debug(message = nil, &block) ⇒ Object

Log a DEBUG message.

See #info for more information.



247
248
249
 
# File 'lib/swiftcore/LoggerInterface.rb', line 247

def debug(message = nil, &block)
  add(DEBUG, message, nil, &block)
end

#debug? ⇒ Boolean

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

Returns:

  • (Boolean) 


224
 
# File 'lib/swiftcore/LoggerInterface.rb', line 224

def debug?; @level <= DEBUG; end

#error(message = nil, &block) ⇒ Object

Log an ERROR message.

See #info for more information.



291
292
293
 
# File 'lib/swiftcore/LoggerInterface.rb', line 291

def error(message = nil, &block)
  add(ERROR, message, nil, &block)
end

#error? ⇒ Boolean

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

Returns:

  • (Boolean) 


236
 
# File 'lib/swiftcore/LoggerInterface.rb', line 236

def error?; @level <= ERROR; end

#fatal(message = nil, &block) ⇒ Object

Log a FATAL message.

See #info for more information.



300
301
302
 
# File 'lib/swiftcore/LoggerInterface.rb', line 300

def fatal(message = nil, &block)
  add(FATAL, message, nil, &block)
end

#fatal? ⇒ Boolean

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

Returns:

  • (Boolean) 


240
 
# File 'lib/swiftcore/LoggerInterface.rb', line 240

def fatal?; @level <= FATAL; end

#info(message = nil, &block) ⇒ Object

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.



273
274
275
 
# File 'lib/swiftcore/LoggerInterface.rb', line 273

def info(message = nil, &block)
  add(INFO, message, nil, &block)
end

#info? ⇒ Boolean

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

Returns:

  • (Boolean) 


228
 
# File 'lib/swiftcore/LoggerInterface.rb', line 228

def info?; @level <= INFO; end

#progname ⇒ Object 



204
205
206
 
# File 'lib/swiftcore/LoggerInterface.rb', line 204

def progname
  @service
end

#progname=(name) ⇒ Object 



200
201
202
 
# File 'lib/swiftcore/LoggerInterface.rb', line 200

def progname=(name)
  @service = name
end

#unknown(message = nil, &block) ⇒ Object

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

See #info for more information.



310
311
312
 
# File 'lib/swiftcore/LoggerInterface.rb', line 310

def unknown(message = nil, &block)
  add(UNKNOWN, message, nil, &block)
end

#warn(message = nil, &block) ⇒ Object

Log a WARN message.

See #info for more information.



282
283
284
 
# File 'lib/swiftcore/LoggerInterface.rb', line 282

def warn(message = nil, &block)
  add(WARN, message, nil, &block)
end

#warn? ⇒ Boolean

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

Returns:

  • (Boolean) 


232
 
# File 'lib/swiftcore/LoggerInterface.rb', line 232

def warn?; @level <= WARN; end