Object
Simple logging utility.
NAKAMURA, Hiroshi <nakahiro@sarion.co.jp>
NAKAMURA, Hiroshi and Gavin Sinclair
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.
$Id: logger.rb 22283 2009-02-13 10:18:12Z shyouhei $
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
.
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.
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 = open('foo.log', File::WRONLY | File::APPEND | File::CREAT) logger = Logger.new(file)
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)
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')
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 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!' }
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. 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.
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.
Logger.new(name, shift_age = 7, shift_size = 1048576) Logger.new(name, shift_age = 'weekly')
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 256 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 336 def <<(msg) unless @logdev.nil? @logdev.write(msg) end end
Logger#add(severity, message = nil, progname = nil) { ... }
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.
But on the OS which supports multi I/O, records possibly be mixed.
# File logger.rb, line 312 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 417 def close @logdev.close if @logdev end
# File logger.rb, line 201 def datetime_format @default_formatter.datetime_format end
Logging date-time format (string passed to strftime
).
# File logger.rb, line 197 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 347 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 217 def debug?; @level <= DEBUG; end
Log an ERROR
message.
See info for more information.
# File logger.rb, line 391 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 229 def error?; @level <= ERROR; end
Log a FATAL
message.
See info for more information.
# File logger.rb, line 400 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 233 def fatal?; @level <= FATAL; end
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 373 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 221 def info?; @level <= INFO; end
Log an UNKNOWN
message. This will be printed no matter what
the logger level.
See info for more information.
# File logger.rb, line 410 def unknown(progname = nil, &block) add(UNKNOWN, nil, progname, &block) end
Log a WARN
message.
See info for more information.
# File logger.rb, line 382 def warn(progname = nil, &block) add(WARN, nil, progname, &block) end