Simple logging utility.

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:

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.