Maintenance of Ruby 2.0.0 ended on February 24, 2016. Read more
Object
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:
UNKNOWN
An unknown message that should always be logged.
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.
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) } logger.info(input)
This creates a Logger that outputs to the
standard output stream, with a level of WARN
:
require 'logger' logger = Logger.new(STDOUT) logger.level = Logger::WARN logger.debug("Created logger") logger.info("Program started") logger.warn("Nothing to do!") path = "a_non_existent_file" begin File.foreach(path) do |line| unless line =~ /^(\w+) = (.*)$/ logger.error("Line in wrong format: #{line.chomp}") end end rescue => err logger.fatal("Caught exception; exiting") logger.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.
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.
The options below give you various choices, in more or less increasing complexity.
Create a logger which logs messages to STDERR/STDOUT.
logger = Logger.new(STDERR) logger = Logger.new(STDOUT)
Create a logger for the file which has the specified name.
logger = Logger.new('logfile.log')
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 = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT) logger = Logger.new(file)
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 = Logger.new('foo.log', 10, 1024000)
Create a logger which ages the logfile daily/weekly/monthly.
logger = Logger.new('foo.log', 'daily') logger = Logger.new('foo.log', 'weekly') logger = Logger.new('foo.log', 'monthly')
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.
Message in a block.
logger.fatal { "Argument 'foo' not given." }
Message as a string.
logger.error "Argument #{@foo} mismatch."
With progname.
logger.info('initialize') { "Initializing..." }
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.
logger.close
Original interface.
logger.sev_threshold = Logger::WARN
Log4r (somewhat) compatible interface.
logger.level = Logger::INFO # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
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, you may change the overall format via the formatter= method.
logger.formatter = proc do |severity, datetime, progname, msg| "#{datetime}: #{msg}\n" end # e.g. "2005-09-22 08:51:08 +0900: hello world"
Logging formatter, as a Proc
that will take four arguments and
return the formatted message. The arguments are:
severity
The Severity of the log message.
time
A Time instance representing when the message was logged.
progname
The progname configured, or passed to the logger method.
msg
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.
logdev
The log device. This is a filename (String) or IO object (typically
STDOUT
, STDERR
, or an open file).
shift_age
Number of old log files to keep, or frequency of rotation
(daily
, weekly
or monthly
).
shift_size
Maximum logfile size (only applies when shift_age
is a
number).
Create an instance.
# File logger.rb, line 311 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) end end
Dump given message to the log device without any formatting. If no log
device exists, return nil
.
# File logger.rb, line 390 def <<(msg) unless @logdev.nil? @logdev.write(msg) end end
severity
Severity. Constants are defined in Logger namespace: DEBUG
,
INFO
, WARN
, ERROR
,
FATAL
, or UNKNOWN
.
message
The log message. A String or Exception.
progname
Program name string. Can be omitted. Treated as a message if no
message
and block
are given.
block
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.
If the OS supports multi I/O, records possibly may be mixed.
# File logger.rb, line 366 def add(severity, message = nil, progname = nil, &block) severity ||= UNKNOWN if @logdev.nil? or severity < @level return true end progname ||= @progname if message.nil? if block_given? message = yield else message = progname progname = @progname end end @logdev.write( format_message(format_severity(severity), Time.now, progname, message)) true end
Close the logging device.
# File logger.rb, line 479 def close @logdev.close if @logdev end
Returns the date format being used. See datetime_format=
# File logger.rb, line 250 def datetime_format @default_formatter.datetime_format end
Set date-time format.
datetime_format
A string suitable for passing to strftime
.
# File logger.rb, line 245 def datetime_format=(datetime_format) @default_formatter.datetime_format = datetime_format end
Log a DEBUG
message.
See info for more information.
# File logger.rb, line 401 def debug(progname = nil, &block) add(DEBUG, nil, progname, &block) end
Returns true
iff the current severity level allows for the
printing of DEBUG
messages.
# File logger.rb, line 273 def debug?; @level <= DEBUG; end
Log an ERROR
message.
See info for more information.
# File logger.rb, line 453 def error(progname = nil, &block) add(ERROR, nil, progname, &block) end
Returns true
iff the current severity level allows for the
printing of ERROR
messages.
# File logger.rb, line 285 def error?; @level <= ERROR; end
Log a FATAL
message.
See info for more information.
# File logger.rb, line 462 def fatal(progname = nil, &block) add(FATAL, nil, progname, &block) end
Returns true
iff the current severity level allows for the
printing of FATAL
messages.
# File logger.rb, line 289 def fatal?; @level <= FATAL; end
Log an INFO
message.
message
The message to log; does not need to be a String.
progname
In the block form, this is the progname to use in the log message. The default can be set with progname=.
block
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.
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 progname= as well).
See add.
# File logger.rb, line 435 def info(progname = nil, &block) add(INFO, nil, progname, &block) end
Returns true
iff the current severity level allows for the
printing of INFO
messages.
# File logger.rb, line 277 def info?; @level <= INFO; end
Log an UNKNOWN
message. This will be printed no matter what
the logger's level is.
See info for more information.
# File logger.rb, line 472 def unknown(progname = nil, &block) add(UNKNOWN, nil, progname, &block) end
Log a WARN
message.
See info for more information.
# File logger.rb, line 444 def warn(progname = nil, &block) add(WARN, nil, progname, &block) end