Class Logger
In: lib/logger.rb
Parent: Object

Simple logging utility.

Author:NAKAMURA, Hiroshi <nakahiro@sarion.co.jp>
Documentation:NAKAMURA, Hiroshi and Gavin Sinclair
License:You can redistribute it and/or modify it under the same terms of Ruby‘s license; either the dual license version in 2003, or any later version.
Revision:$Id: logger.rb 22285 2009-02-13 10:19:04Z shyouhei $

Description

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 = Logger.new(STDOUT)
  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.

Features

There are several interesting features that Logger provides, like auto-rolling of log files, setting the format of log messages, and specifying a program name in conjunction with the message. The next section shows you how to achieve these things.

HOWTOs

How to create a logger

The options below give you various choices, in more or less increasing complexity.

  1. Create a logger which logs messages to STDERR/STDOUT.
      logger = Logger.new(STDERR)
      logger = Logger.new(STDOUT)
    
  2. Create a logger for the file which has the specified name.
      logger = Logger.new('logfile.log')
    
  3. Create a logger for the specified file.
      file = File.open('foo.log', File::WRONLY | File::APPEND)
      # To create new (and to remove old) logfile, add File::CREAT like;
      #   file = open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
      logger = Logger.new(file)
    
  4. Create a logger which ages logfile once it reaches a certain size. Leave 10 "old log files" and each file is about 1,024,000 bytes.
      logger = Logger.new('foo.log', 10, 1024000)
    
  5. Create a logger which ages logfile daily/weekly/monthly.
      logger = Logger.new('foo.log', 'daily')
      logger = Logger.new('foo.log', 'weekly')
      logger = Logger.new('foo.log', 'monthly')
    

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!' }
    

How to close a logger

     logger.close

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
    

Format

Log messages are rendered in the output stream in a certain format. The default format and a sample are shown below:

Log format:

  SeverityID, [Date Time mSec #pid] SeverityLabel -- ProgName: message

Log sample:

  I, [Wed Mar 03 02:34:24 JST 1999 895701 #19074]  INFO -- Main: info.

You may change the date and time format in this manner:

  logger.datetime_format = "%Y-%m-%d %H:%M:%S"
        # e.g. "2004-01-03 00:54:26"

There is currently no supported way to change the overall format, but you may have some luck hacking the Format constant.

Methods

<<   add   close   datetime_format   datetime_format=   debug   debug?   error   error?   fatal   fatal?   format_message   format_severity   info   info?   log   new   unknown   warn   warn?  

Included Modules

Severity

Classes and Modules

Module Logger::Severity
Class Logger::Application
Class Logger::Error
Class Logger::Formatter
Class Logger::LogDevice
Class Logger::ShiftingError

Constants

VERSION = "1.2.6"
ProgName = "#{name.chomp(",v")}/#{rev}"
SEV_LABEL = %w(DEBUG INFO WARN ERROR FATAL ANY)   Severity label for logging. (max 5 char)

External Aliases

level -> sev_threshold
level= -> sev_threshold=

Attributes

formatter  [RW]  Logging formatter. formatter#call is invoked with 4 arguments; severity, time, progname and msg for each log. Bear in mind that time is a Time and msg is an Object that user passed and it could not be a String. It is expected to return a logdev#write-able Object. Default formatter is used when no formatter is set.
level  [RW]  Logging severity threshold (e.g. Logger::INFO).
progname  [RW]  Logging program name.

Public Class methods

Synopsis

  Logger.new(name, shift_age = 7, shift_size = 1048576)
  Logger.new(name, shift_age = 'weekly')

Args

logdev:The log device. This is a filename (String) or IO object (typically STDOUT, STDERR, or an open file).
shift_age:Number of old log files to keep, or frequency of rotation (daily, weekly or monthly).
shift_size:Maximum logfile size (only applies when shift_age is a number).

Description

Create an instance.

[Source]

     # File lib/logger.rb, line 256
256:   def initialize(logdev, shift_age = 0, shift_size = 1048576)
257:     @progname = nil
258:     @level = DEBUG
259:     @default_formatter = Formatter.new
260:     @formatter = nil
261:     @logdev = nil
262:     if logdev
263:       @logdev = LogDevice.new(logdev, :shift_age => shift_age,
264:         :shift_size => shift_size)
265:     end
266:   end

Public Instance methods

Dump given message to the log device without any formatting. If no log device exists, return nil.

[Source]

     # File lib/logger.rb, line 336
336:   def <<(msg)
337:     unless @logdev.nil?
338:       @logdev.write(msg)
339:     end
340:   end

Synopsis

  Logger#add(severity, message = nil, progname = nil) { ... }

Args

severity:Severity. Constants are defined in Logger namespace: DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN.
message:The log message. A String or Exception.
progname:Program name string. Can be omitted. Treated as a message if no message and block are given.
block:Can be omitted. Called to get a message string if message is nil.

Return

true if successful, false otherwise.

When the given severity is not high enough (for this particular logger), log no message, and return true.

Description

Log a message if the given severity is high enough. This is the generic logging method. Users will be more inclined to use debug, info, warn, error, and fatal.

Message format: message can be any object, but it has to be converted to a String in order to log it. Generally, inspect is used if the given object is not a String. A special case is an Exception object, which will be printed in detail, including message, class, and backtrace. See msg2str for the implementation if required.

Bugs

  • Logfile is not locked.
  • Append open does not need to lock file.
  • But on the OS which supports multi I/O, records possibly be mixed.

[Source]

     # File lib/logger.rb, line 312
312:   def add(severity, message = nil, progname = nil, &block)
313:     severity ||= UNKNOWN
314:     if @logdev.nil? or severity < @level
315:       return true
316:     end
317:     progname ||= @progname
318:     if message.nil?
319:       if block_given?
320:         message = yield
321:       else
322:         message = progname
323:         progname = @progname
324:       end
325:     end
326:     @logdev.write(
327:       format_message(format_severity(severity), Time.now, progname, message))
328:     true
329:   end

Close the logging device.

[Source]

     # File lib/logger.rb, line 417
417:   def close
418:     @logdev.close if @logdev
419:   end

[Source]

     # File lib/logger.rb, line 201
201:   def datetime_format
202:     @default_formatter.datetime_format
203:   end

Logging date-time format (string passed to strftime).

[Source]

     # File lib/logger.rb, line 197
197:   def datetime_format=(datetime_format)
198:     @default_formatter.datetime_format = datetime_format
199:   end

Log a DEBUG message.

See info for more information.

[Source]

     # File lib/logger.rb, line 347
347:   def debug(progname = nil, &block)
348:     add(DEBUG, nil, progname, &block)
349:   end

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

[Source]

     # File lib/logger.rb, line 217
217:   def debug?; @level <= DEBUG; end

Log an ERROR message.

See info for more information.

[Source]

     # File lib/logger.rb, line 391
391:   def error(progname = nil, &block)
392:     add(ERROR, nil, progname, &block)
393:   end

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

[Source]

     # File lib/logger.rb, line 229
229:   def error?; @level <= ERROR; end

Log a FATAL message.

See info for more information.

[Source]

     # File lib/logger.rb, line 400
400:   def fatal(progname = nil, &block)
401:     add(FATAL, nil, progname, &block)
402:   end

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

[Source]

     # File lib/logger.rb, line 233
233:   def fatal?; @level <= FATAL; end

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.

[Source]

     # File lib/logger.rb, line 373
373:   def info(progname = nil, &block)
374:     add(INFO, nil, progname, &block)
375:   end

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

[Source]

     # File lib/logger.rb, line 221
221:   def info?; @level <= INFO; end
log(severity, message = nil, progname = nil, &block)

Alias for add

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

See info for more information.

[Source]

     # File lib/logger.rb, line 410
410:   def unknown(progname = nil, &block)
411:     add(UNKNOWN, nil, progname, &block)
412:   end

Log a WARN message.

See info for more information.

[Source]

     # File lib/logger.rb, line 382
382:   def warn(progname = nil, &block)
383:     add(WARN, nil, progname, &block)
384:   end

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

[Source]

     # File lib/logger.rb, line 225
225:   def warn?; @level <= WARN; end

Private Instance methods

[Source]

     # File lib/logger.rb, line 430
430:   def format_message(severity, datetime, progname, msg)
431:     (@formatter || @default_formatter).call(severity, datetime, progname, msg)
432:   end

[Source]

     # File lib/logger.rb, line 426
426:   def format_severity(severity)
427:     SEV_LABEL[severity] || 'ANY'
428:   end

[Validate]