Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

In Files

  • 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:


an unhandleable error that results in a program crash


a handleable error condition


a warning


generic (useful) information about system operation


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.


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!")

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

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.


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.


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


Setting severity threshold

  1. Original interface.

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

    logger.level = Logger::INFO


Log messages are rendered in the output stream in a certain format by default. 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"

You may change the overall format with #formatter method.

logger.formatter = proc { |severity, datetime, progname, msg|
  "#{datetime}: #{msg}\n"
      # e.g. "Thu Sep 22 08:51:08 GMT+9:00 2005: hello world"



Severity label for logging. (max 5 char)




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.


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


Logging program name.


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


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

Public Class Methods

new(logdev, shift_age = 0, shift_size = 1048576) click to toggle source


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



The log device. This is a filename (String) or IO object (typically STDOUT, STDERR, or an open file).


Number of old log files to keep, or frequency of rotation (daily, weekly or monthly).


Maximum logfile size (only applies when shift_age is a number).


Create an instance.

               # File logger.rb, line 268
def initialize(logdev, shift_age = 0, shift_size = 1048576)
  @progname = nil
  @level = DEBUG
  @default_formatter = Formatter.new
  @formatter = nil
  @logdev = nil
  if logdev
    @logdev = LogDevice.new(logdev, :shift_age => shift_age,
      :shift_size => shift_size)

Public Instance Methods

<<(msg) click to toggle source

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

               # File logger.rb, line 348
def <<(msg)
  unless @logdev.nil?
add(severity, message = nil, progname = nil, &block) click to toggle source


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



Severity. Constants are defined in Logger namespace: DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN.


The log message. A String or Exception.


Program name string. Can be omitted. Treated as a message if no message and block are given.


Can be omitted. Called to get a message string if message is nil.


true if successful, false otherwise.

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


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.


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

               # File logger.rb, line 324
def add(severity, message = nil, progname = nil, &block)
  severity ||= UNKNOWN
  if @logdev.nil? or severity < @level
    return true
  progname ||= @progname
  if message.nil?
    if block_given?
      message = yield
      message = progname
      progname = @progname
    format_message(format_severity(severity), Time.now, progname, message))
Also aliased as: log
close() click to toggle source

Close the logging device.

               # File logger.rb, line 429
def close
  @logdev.close if @logdev
datetime_format() click to toggle source
               # File logger.rb, line 213
def datetime_format
datetime_format=(datetime_format) click to toggle source

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

               # File logger.rb, line 209
def datetime_format=(datetime_format)
  @default_formatter.datetime_format = datetime_format
debug(progname = nil, &block) click to toggle source

Log a DEBUG message.

See info for more information.

               # File logger.rb, line 359
def debug(progname = nil, &block)
  add(DEBUG, nil, progname, &block)
debug?() click to toggle source

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

               # File logger.rb, line 229
def debug?; @level <= DEBUG; end
error(progname = nil, &block) click to toggle source

Log an ERROR message.

See info for more information.

               # File logger.rb, line 403
def error(progname = nil, &block)
  add(ERROR, nil, progname, &block)
error?() click to toggle source

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

               # File logger.rb, line 241
def error?; @level <= ERROR; end
fatal(progname = nil, &block) click to toggle source

Log a FATAL message.

See info for more information.

               # File logger.rb, line 412
def fatal(progname = nil, &block)
  add(FATAL, nil, progname, &block)
fatal?() click to toggle source

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

               # File logger.rb, line 245
def fatal?; @level <= FATAL; end
info(progname = 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.


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


See add.

               # File logger.rb, line 385
def info(progname = nil, &block)
  add(INFO, nil, progname, &block)
info?() click to toggle source

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

               # File logger.rb, line 233
def info?; @level <= INFO; end
log(severity, message = nil, progname = nil, &block) click to toggle source
Alias for: add
unknown(progname = 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 logger.rb, line 422
def unknown(progname = nil, &block)
  add(UNKNOWN, nil, progname, &block)
warn(progname = nil, &block) click to toggle source

Log a WARN message.

See info for more information.

               # File logger.rb, line 394
def warn(progname = nil, &block)
  add(WARN, nil, progname, &block)
warn?() click to toggle source

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

               # File logger.rb, line 237
def warn?; @level <= WARN; end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus