class Logger


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 or higher will be printed.

The levels are:


An unknown message that should always be logged.


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:"User-input: #{input.dump}")"User-input: %p" % input)

You can use formatter= for escaping all data.

original_formatter =
logger.formatter = proc { |severity, datetime, progname, msg|, datetime, progname, msg.dump)


This creates a Logger that outputs to the standard output stream, with a level of WARN:

require 'logger'

logger =
logger.level = Logger::WARN

logger.debug("Created logger")"Program started")
logger.warn("Nothing to do!")

path = "a_non_existent_file"

  File.foreach(path) do |line|
    unless line =~ /^(\w+) = (.*)$/
      logger.error("Line in wrong format: #{line.chomp}")
rescue => err
  logger.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 =
  2. Create a logger for the file which has the specified name.

    logger ='logfile.log')
  3. Create a logger for the specified file.

    file ='foo.log', File::WRONLY | File::APPEND)
    # To create new logfile, add File::CREAT like:
    # file ='foo.log', File::WRONLY | File::APPEND | File::CREAT)
    logger =
  4. Create a logger which ages the logfile once it reaches a certain size. Leave 10 “old” log files where each file is about 1,024,000 bytes.

    logger ='foo.log', 10, 1024000)
  5. Create a logger which ages the logfile daily/weekly/monthly.

    logger ='foo.log', 'daily')
    logger ='foo.log', 'weekly')
    logger ='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 a block.

    logger.fatal { "Argument 'foo' not given." }
  2. Message as a string.

    logger.error "Argument #{@foo} mismatch."
  3. With progname.'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
  3. Symbol or String (case insensitive)

    logger.level = :info
    logger.level = 'INFO'
    # :debug < :info < :warn < :error < :fatal < :unknown
  4. Constructor, level: Logger::INFO), level: :info), level: '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, [DateTime #pid] SeverityLabel -- ProgName: message

Log sample:

I, [1999-03-03T02:34:24.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 via the constructor., datetime_format: '%Y-%m-%d %H:%M:%S')

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

logger.formatter = proc do |severity, datetime, progname, msg|
  "#{datetime}: #{msg}\n"
# e.g. "2005-09-22 08:51:08 +0900: hello world"

or via the constructor., formatter: proc {|severity, datetime, progname, msg|
  "#{datetime}: #{msg}\n"



Severity label for logging (max 5 chars).



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

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.


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


Program name to include in log messages.


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

Public Class Methods

new(logdev, shift_age = 0, shift_size = 1048576) click to toggle source
new(logdev, shift_age = 'weekly')
new(logdev, level: :info)
new(logdev, progname: 'progname')
new(logdev, formatter: formatter)
new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')



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). Default value is 0, which disables log file rotation.


Maximum logfile size in bytes (only applies when shift_age is a positive Integer). Defaults to 1048576 (1MB).


Logging severity threshold. Default values is Logger::DEBUG.


Program name to include in log messages. Default value is nil.


Logging formatter. Default values is an instance of Logger::Formatter.


Date and time format. Default value is '%Y-%m-%d %H:%M:%S'.


Use binary mode on the log device. Default value is false.


The log file suffix format for daily, weekly or monthly rotation. Default is '%Y%m%d'.


Create an instance.

# File lib/logger.rb, line 379
def initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG,
               progname: nil, formatter: nil, datetime_format: nil,
               binmode: false, shift_period_suffix: '%Y%m%d')
  self.level = level
  self.progname = progname
  @default_formatter =
  self.datetime_format = datetime_format
  self.formatter = formatter
  @logdev = nil
  if logdev
    @logdev =, shift_age: shift_age,
      shift_size: shift_size,
      shift_period_suffix: shift_period_suffix,
      binmode: binmode)

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 lib/logger.rb, line 484
def <<(msg)
Logger#add(severity, message = nil, progname = nil) { ... } click to toggle source



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.


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.

  • If the OS supports multi I/O, records possibly may be mixed.

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

Close the logging device.

# File lib/logger.rb, line 571
def close
datetime_format() click to toggle source

Returns the date format being used. See datetime_format=

# File lib/logger.rb, line 284
def datetime_format
datetime_format=(datetime_format) click to toggle source

Set date-time format.


A string suitable for passing to strftime.

# File lib/logger.rb, line 279
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 lib/logger.rb, line 493
def debug(progname = nil, &block)
  add(DEBUG, nil, progname, &block)
debug!() click to toggle source

Sets the severity to DEBUG.

# File lib/logger.rb, line 310
def debug!; self.level = DEBUG; end
debug?() click to toggle source

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

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

Log an ERROR message.

See info for more information.

# File lib/logger.rb, line 545
def error(progname = nil, &block)
  add(ERROR, nil, progname, &block)
error!() click to toggle source

Sets the severity to ERROR.

# File lib/logger.rb, line 331
def error!; self.level = ERROR; end
error?() click to toggle source

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

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

Log a FATAL message.

See info for more information.

# File lib/logger.rb, line 554
def fatal(progname = nil, &block)
  add(FATAL, nil, progname, &block)
fatal!() click to toggle source

Sets the severity to FATAL.

# File lib/logger.rb, line 338
def fatal!; self.level = FATAL; end
fatal?() click to toggle source

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

# File lib/logger.rb, line 335
def fatal?; level <= FATAL; end
info(message) click to toggle source
info(progname, &block)

Log an INFO message.


The message to log; does not need to be a String.


In the block form, this is the progname to use in the log message. The default can be set with progname=.


Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Examples"MainApp") { "Received connection from #{ip}" }
# ... "Waiting for input from user"
# ... { "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 progname= as well).


See add.

# File lib/logger.rb, line 527
def info(progname = nil, &block)
  add(INFO, nil, progname, &block)
info!() click to toggle source

Sets the severity to INFO.

# File lib/logger.rb, line 317
def info!; self.level = INFO; end
info?() click to toggle source

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

# File lib/logger.rb, line 314
def info?; level <= INFO; end
level=(severity) click to toggle source

Set logging severity threshold.


The Severity of the log message.

# File lib/logger.rb, line 250
def level=(severity)
  if severity.is_a?(Integer)
    @level = severity
    case severity.to_s.downcase
    when 'debug'
      @level = DEBUG
    when 'info'
      @level = INFO
    when 'warn'
      @level = WARN
    when 'error'
      @level = ERROR
    when 'fatal'
      @level = FATAL
    when 'unknown'
      @level = UNKNOWN
      raise ArgumentError, "invalid log level: #{severity}"
Also aliased as: sev_threshold=
log(severity, message = nil, progname = nil)
Alias for: add
Logger#reopen click to toggle source



The log device. This is a filename (String) or IO object (typically STDOUT, STDERR, or an open file). reopen the same filename if it is nil, do nothing for IO. Default is nil.


Reopen a log device.

# File lib/logger.rb, line 412
def reopen(logdev = nil)
Alias for: level=
unknown(progname = nil, &block) click to toggle source

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

See info for more information.

# File lib/logger.rb, line 564
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 lib/logger.rb, line 536
def warn(progname = nil, &block)
  add(WARN, nil, progname, &block)
warn!() click to toggle source

Sets the severity to WARN.

# File lib/logger.rb, line 324
def warn!; self.level = WARN; end
warn?() click to toggle source

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

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

Private Instance Methods

format_message(severity, datetime, progname, msg) click to toggle source
# File lib/logger.rb, line 584
def format_message(severity, datetime, progname, msg)
  (@formatter || @default_formatter).call(severity, datetime, progname, msg)
format_severity(severity) click to toggle source
# File lib/logger.rb, line 580
def format_severity(severity)
  SEV_LABEL[severity] || 'ANY'