Class: Logger
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
Severity
|
|
Inherits: | Object |
Defined in: | lib/logger.rb |
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
-
Symbol or String (case insensitive)
logger.level = :info logger.level = '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"
Constant Summary
-
ProgName =
# File 'lib/logger.rb', line 219"#{name}/#{rev}".freeze
-
SEV_LABEL =
::Logger::Severity label for logging (max 5 chars).
%w(DEBUG INFO WARN ERROR FATAL ANY).each(&:freeze).freeze
-
VERSION =
# File 'lib/logger.rb', line 211"1.2.7"
Severity - Included
Class Method Summary
-
.new(logdev, shift_age = 7, shift_size = 1048576) ⇒ Logger
constructor
Args.
Instance Attribute Summary
-
#datetime_format
rw
Returns the date format being used.
-
#datetime_format=(datetime_format)
rw
Set date-time format.
-
#formatter
rw
Logging formatter, as a
Proc
that will take four arguments and return the formatted message. -
#level
(also: #sev_threshold)
rw
Logging severity threshold (e.g.
-
#level=(severity)
(also: #sev_threshold=)
rw
Set logging severity threshold.
-
#progname
rw
Program name to include in log messages.
-
#sev_threshold
rw
Alias for #level.
-
#debug? ⇒ Boolean
readonly
Returns
true
iff the current severity level allows for the printing ofDEBUG
messages. -
#error? ⇒ Boolean
readonly
Returns
true
iff the current severity level allows for the printing ofERROR
messages. -
#fatal? ⇒ Boolean
readonly
Returns
true
iff the current severity level allows for the printing ofFATAL
messages. -
#info? ⇒ Boolean
readonly
Returns
true
iff the current severity level allows for the printing ofINFO
messages. -
#warn? ⇒ Boolean
readonly
Returns
true
iff the current severity level allows for the printing ofWARN
messages.
Instance Method Summary
-
#<<(msg)
Dump given message to the log device without any formatting.
-
#add(severity, message = nil, progname = nil)
(also: #log)
Args.
-
#close
Close the logging device.
-
#debug(progname = nil, &block)
readonly
Log a
DEBUG
message. -
#error(progname = nil, &block)
readonly
Log an
ERROR
message. -
#fatal(progname = nil, &block)
readonly
Log a
FATAL
message. -
#info(message)
readonly
Log an
INFO
message. -
#log(severity, message = nil, progname = nil)
Alias for #add.
-
#reopen
Args.
-
#unknown(progname = nil, &block)
Log an
UNKNOWN
message. -
#warn(progname = nil, &block)
readonly
Log a
WARN
message. - #format_message(severity, datetime, progname, msg) private
- #format_severity(severity) private
Constructor Details
.new(logdev, shift_age = 7, shift_size = 1048576) ⇒ Logger
.new(logdev, shift_age = 'weekly') ⇒ Logger
Logger
.new(logdev, shift_age = 'weekly') ⇒ Logger
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.
Instance Attribute Details
#datetime_format (rw)
Returns the date format being used. See #datetime_format=
# File 'lib/logger.rb', line 285
def datetime_format @default_formatter.datetime_format end
#datetime_format=(datetime_format) (rw)
Set date-time format.
- #datetime_format
-
A string suitable for passing to
strftime
.
# File 'lib/logger.rb', line 280
def datetime_format=(datetime_format) @default_formatter.datetime_format = datetime_format end
#debug? ⇒ Boolean
(readonly)
Returns true
iff the current severity level allows for the printing of DEBUG
messages.
# File 'lib/logger.rb', line 308
def debug?; @level <= DEBUG; end
#error? ⇒ Boolean
(readonly)
Returns true
iff the current severity level allows for the printing of ERROR
messages.
# File 'lib/logger.rb', line 320
def error?; @level <= ERROR; end
#fatal? ⇒ Boolean
(readonly)
Returns true
iff the current severity level allows for the printing of FATAL
messages.
# File 'lib/logger.rb', line 324
def fatal?; @level <= FATAL; end
#formatter (rw)
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.
# File 'lib/logger.rb', line 301
attr_accessor :formatter
#info? ⇒ Boolean
(readonly)
Returns true
iff the current severity level allows for the printing of INFO
messages.
# File 'lib/logger.rb', line 312
def info?; @level <= INFO; end
#level (rw) Also known as: #sev_threshold
Logging severity threshold (e.g. Logger::INFO
).
# File 'lib/logger.rb', line 245
attr_reader :level
#level=(severity) (rw) Also known as: #sev_threshold=
Set logging severity threshold.
severity
-
The Severity of the log message.
# File 'lib/logger.rb', line 250
def level=(severity) if severity.is_a?(Integer) @level = severity else _severity = severity.to_s.downcase case _severity when 'debug'.freeze @level = DEBUG when 'info'.freeze @level = INFO when 'warn'.freeze @level = WARN when 'error'.freeze @level = ERROR when 'fatal'.freeze @level = FATAL when 'unknown'.freeze @level = UNKNOWN else raise ArgumentError, "invalid log level: #{severity}" end end end
#progname (rw)
Program name to include in log messages.
# File 'lib/logger.rb', line 275
attr_accessor :progname
#sev_threshold (rw)
Alias for #level.
# File 'lib/logger.rb', line 303
alias sev_threshold level
#warn? ⇒ Boolean
(readonly)
Returns true
iff the current severity level allows for the printing of WARN
messages.
# File 'lib/logger.rb', line 316
def warn?; @level <= WARN; end
Instance Method Details
#<<(msg)
Dump given message to the log device without any formatting. If no log device exists, return nil
.
# File 'lib/logger.rb', line 443
def <<(msg) unless @logdev.nil? @logdev.write(msg) end end
#add(severity, message = nil, progname = nil) Also known as: #log
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.
# File 'lib/logger.rb', line 419
def add(severity, = nil, progname = nil) 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
Close the logging device.
# File 'lib/logger.rb', line 532
def close @logdev.close if @logdev end
#debug(progname = nil, &block) (readonly)
Log a DEBUG
message.
See #info for more information.
#error(progname = nil, &block) (readonly)
Log an ERROR
message.
See #info for more information.
#fatal(progname = nil, &block) (readonly)
Log a FATAL
message.
See #info for more information.
#format_message(severity, datetime, progname, msg) (private)
[ GitHub ]#format_severity(severity) (private)
[ GitHub ]# File 'lib/logger.rb', line 541
def format_severity(severity) SEV_LABEL[severity] || 'ANY' end
#info(message) (readonly)
#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.
#log(severity, message = nil, progname = nil)
Alias for #add.
# File 'lib/logger.rb', line 437
alias log add
#reopen
#reopen(logdev)
Args
logdev
-
The log device. This is a filename (String) or IO object (typically
STDOUT
,STDERR
, or an open file).
Description
Reopen a log device.
# File 'lib/logger.rb', line 373
def reopen(logdev = nil) @logdev.reopen(logdev) self end
#unknown(progname = nil, &block)
Log an UNKNOWN
message. This will be printed no matter what the logger's level is.
See #info for more information.
#warn(progname = nil, &block) (readonly)
Log a WARN
message.
See #info for more information.