The Logger class provides a simple but sophisticated logging utility that you can use to output messages.

The messages have associated levels, such as INFO or ERROR that indicate their importance. You can then give the Logger a level, and only messages at that level of higher will be printed.

The levels 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

For instance, in a production system, you may have your Logger set to INFO or even WARN When you are developing the system, however, you probably want to know about the program’s internal state, and would set the Logger to DEBUG.

Note: Logger does not escape or sanitize any messages passed to it. Developers should be aware of when potentially malicious data (user-input) is passed to Logger, and manually escape the untrusted data:

logger.info("User-input: #{input.dump}")
logger.info("User-input: %p" % input)

You can use #formatter= for escaping all data.

original_formatter = Logger::Formatter.new
logger.formatter = proc { |severity, datetime, progname, msg|
  original_formatter.call(severity, datetime, progname, msg.dump)


This creates a logger to the standard output stream, with a level of WARN

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)
  1. 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!' }

The block form allows you to create potentially complex log messages, but to delay their evaluation until and unless the message is logged. For example, if we have the following:

logger.debug { "This is a " + potentially + " expensive operation" }

If the logger’s level is INFO or higher, no debug messages will be logged, and the entire block will not even be evaluated. Compare to this:

logger.debug("This is a " + potentially + " expensive operation")

Here, the string concatenation is done every time, even if the log level is not set to show the debug message.

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 via #datetime_format=

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

Or, you may change the overall format with #formatter= method.

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



ProgName = "#{name}/#{rev}"

VERSION = "1.2.7"


[RW] sev_threshold=

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

[RW] sev_threshold

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

[RW] formatter

Logging formatter, as a Proc that will take four arguments and return the formatted message. The arguments are:


The Severity of the log message


A Time instance representing when the message was logged


The #progname configured, or passed to the logger method


The Object the user passed to the log message; not necessarily a


The block should return an Object that can be written to the logging device via write. The default formatter is used when no formatter is set.

[RW] progname

program name to include in log messages.

[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 ]

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