Flowdock

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$

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.

Aliases

  • level=
  • level

Constants

SEV_LABEL = %w(DEBUG INFO WARN ERROR FATAL ANY)

ProgName = "#{name.chomp(",v")}/#{rev}"

VERSION = "1.2.6"

Attributes

[RW] formatter

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.

[RW] progname

Logging program name.

[RW] level

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

Show files where this class is defined (1 file)
Register or log in to add new notes.
April 23, 2009
1 thank

Customize Formatting with a Subclass

Instead of passing in a formatter block, you can always create a subclass that defines the format:

require 'logger'

class MyLogger < Logger
  def format_message(severity, datetime, progname, msg)
    "[%s %s] %s\n" % [ severity, datetime.strtftime("%H:%M"), msg ]
  end
end

This can be easier than always passing the same formatter option.