Class: Logger
Overview
Description
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)
Example
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.
Features
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.
HOWTOs
How to create a logger
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')
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.
-
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.
How to close a logger
logger.close
Setting severity threshold
-
Original interface.
logger.sev_threshold = Logger::WARN
-
Log4r (somewhat) compatible interface.
logger.level = Logger::INFO # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
Format
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"
Defined Under Namespace
Modules: Severity Classes: Application, Error, Formatter, LogDevice, ShiftingError
Constant Summary collapse
- VERSION =
"1.2.7"
- ProgName =
"#{name}/#{rev}"
Constants included from Severity
Severity::DEBUG, Severity::ERROR, Severity::FATAL, Severity::INFO, Severity::UNKNOWN, Severity::WARN
Instance Attribute Summary collapse
-
#formatter ⇒ Object
Logging formatter, as a
Proc
that will take four arguments and return the formatted message. -
#level ⇒ Object
(also: #sev_threshold)
Logging severity threshold (e.g.
Logger::INFO
). -
#progname ⇒ Object
Program name to include in log messages.
Instance Method Summary collapse
-
#<<(msg) ⇒ Object
Dump given message to the log device without any formatting.
-
#add(severity, message = nil, progname = nil, &block) ⇒ Object
(also: #log)
:call-seq: Logger#add(severity, message = nil, progname = nil) { … }.
-
#close ⇒ Object
Close the logging device.
-
#datetime_format ⇒ Object
Returns the date format being used.
-
#datetime_format=(datetime_format) ⇒ Object
Set date-time format.
-
#debug(progname = nil, &block) ⇒ Object
Log a
DEBUG
message. -
#debug? ⇒ Boolean
Returns
true
iff the current severity level allows for the printing ofDEBUG
messages. -
#error(progname = nil, &block) ⇒ Object
Log an
ERROR
message. -
#error? ⇒ Boolean
Returns
true
iff the current severity level allows for the printing ofERROR
messages. -
#fatal(progname = nil, &block) ⇒ Object
Log a
FATAL
message. -
#fatal? ⇒ Boolean
Returns
true
iff the current severity level allows for the printing ofFATAL
messages. -
#info(progname = nil, &block) ⇒ Object
:call-seq: info(message) info(progname, &block).
-
#info? ⇒ Boolean
Returns
true
iff the current severity level allows for the printing ofINFO
messages. -
#initialize(logdev, shift_age = 0, shift_size = 1048576) ⇒ Logger
constructor
:call-seq: Logger.new(name, shift_age = 7, shift_size = 1048576) Logger.new(name, shift_age = ‘weekly’).
-
#unknown(progname = nil, &block) ⇒ Object
Log an
UNKNOWN
message. -
#warn(progname = nil, &block) ⇒ Object
Log a
WARN
message. -
#warn? ⇒ Boolean
Returns
true
iff the current severity level allows for the printing ofWARN
messages.
Constructor Details
#initialize(logdev, shift_age = 0, shift_size = 1048576) ⇒ Logger
:call-seq:
Logger.new(name, shift_age = 7, shift_size = 1048576)
Logger.new(name, shift_age = 'weekly')
Args
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
ormonthly
). shift_size
-
Maximum logfile size (only applies when
shift_age
is a number).
Description
Create an instance.
311 312 313 314 315 316 317 318 319 320 321 |
# File 'lib/rubysl/logger/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 |
Instance Attribute Details
#formatter ⇒ Object
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.
266 267 268 |
# File 'lib/rubysl/logger/logger.rb', line 266 def formatter @formatter end |
#level ⇒ Object Also known as: sev_threshold
Logging severity threshold (e.g. Logger::INFO
).
237 238 239 |
# File 'lib/rubysl/logger/logger.rb', line 237 def level @level end |
#progname ⇒ Object
Program name to include in log messages.
240 241 242 |
# File 'lib/rubysl/logger/logger.rb', line 240 def progname @progname end |
Instance Method Details
#<<(msg) ⇒ Object
Dump given message to the log device without any formatting. If no log device exists, return nil
.
388 389 390 391 392 |
# File 'lib/rubysl/logger/logger.rb', line 388 def <<(msg) unless @logdev.nil? @logdev.write(msg) end end |
#add(severity, message = nil, progname = nil, &block) ⇒ Object Also known as: log
:call-seq:
Logger#add(severity, message = nil, progname = nil) { ... }
Args
severity
-
Severity. Constants are defined in Logger namespace:
DEBUG
,INFO
,WARN
,ERROR
,FATAL
, orUNKNOWN
. message
-
The log message. A String or Exception.
progname
-
Program name string. Can be omitted. Treated as a message if no
message
andblock
are given. block
-
Can be omitted. Called to get a message string if
message
is nil.
Return
When the given severity is not high enough (for this particular logger), log no message, and return true
.
Description
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.
Bugs
-
Logfile is not locked.
-
Append open does not need to lock file.
-
If the OS supports multi I/O, records possibly may be mixed.
364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 |
# File 'lib/rubysl/logger/logger.rb', line 364 def add(severity, = nil, progname = nil, &block) severity ||= UNKNOWN if @logdev.nil? or severity < @level return true end progname ||= @progname if .nil? if block_given? = yield else = progname progname = @progname end end @logdev.write( (format_severity(severity), Time.now, progname, )) true end |
#close ⇒ Object
Close the logging device.
477 478 479 |
# File 'lib/rubysl/logger/logger.rb', line 477 def close @logdev.close if @logdev end |
#datetime_format ⇒ Object
Returns the date format being used. See #datetime_format=
250 251 252 |
# File 'lib/rubysl/logger/logger.rb', line 250 def datetime_format @default_formatter.datetime_format end |
#datetime_format=(datetime_format) ⇒ Object
Set date-time format.
datetime_format
-
A string suitable for passing to
strftime
.
245 246 247 |
# File 'lib/rubysl/logger/logger.rb', line 245 def datetime_format=(datetime_format) @default_formatter.datetime_format = datetime_format end |
#debug(progname = nil, &block) ⇒ Object
Log a DEBUG
message.
See #info for more information.
399 400 401 |
# File 'lib/rubysl/logger/logger.rb', line 399 def debug(progname = nil, &block) add(DEBUG, nil, progname, &block) end |
#debug? ⇒ Boolean
Returns true
iff the current severity level allows for the printing of DEBUG
messages.
273 |
# File 'lib/rubysl/logger/logger.rb', line 273 def debug?; @level <= DEBUG; end |
#error(progname = nil, &block) ⇒ Object
Log an ERROR
message.
See #info for more information.
451 452 453 |
# File 'lib/rubysl/logger/logger.rb', line 451 def error(progname = nil, &block) add(ERROR, nil, progname, &block) end |
#error? ⇒ Boolean
Returns true
iff the current severity level allows for the printing of ERROR
messages.
285 |
# File 'lib/rubysl/logger/logger.rb', line 285 def error?; @level <= ERROR; end |
#fatal(progname = nil, &block) ⇒ Object
Log a FATAL
message.
See #info for more information.
460 461 462 |
# File 'lib/rubysl/logger/logger.rb', line 460 def fatal(progname = nil, &block) add(FATAL, nil, progname, &block) end |
#fatal? ⇒ Boolean
Returns true
iff the current severity level allows for the printing of FATAL
messages.
289 |
# File 'lib/rubysl/logger/logger.rb', line 289 def fatal?; @level <= FATAL; end |
#info(progname = nil, &block) ⇒ Object
:call-seq:
info()
info(progname, &block)
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.
Examples
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).
Return
See #add.
433 434 435 |
# File 'lib/rubysl/logger/logger.rb', line 433 def info(progname = nil, &block) add(INFO, nil, progname, &block) end |
#info? ⇒ Boolean
Returns true
iff the current severity level allows for the printing of INFO
messages.
277 |
# File 'lib/rubysl/logger/logger.rb', line 277 def info?; @level <= INFO; end |
#unknown(progname = nil, &block) ⇒ Object
Log an UNKNOWN
message. This will be printed no matter what the logger’s level is.
See #info for more information.
470 471 472 |
# File 'lib/rubysl/logger/logger.rb', line 470 def unknown(progname = nil, &block) add(UNKNOWN, nil, progname, &block) end |
#warn(progname = nil, &block) ⇒ Object
Log a WARN
message.
See #info for more information.
442 443 444 |
# File 'lib/rubysl/logger/logger.rb', line 442 def warn(progname = nil, &block) add(WARN, nil, progname, &block) end |
#warn? ⇒ Boolean
Returns true
iff the current severity level allows for the printing of WARN
messages.
281 |
# File 'lib/rubysl/logger/logger.rb', line 281 def warn?; @level <= WARN; end |