class MLogger
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 of higher will be printed.
The levels 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
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 = MLogger::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 to the standard output stream, with a level of WARN
log = MLogger.new(STDOUT) log.level = MLogger::WARN # as run: log.level = :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.
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 = MLogger.new(STDERR) logger = MLogger.new(STDOUT)
-
Create a logger for the file which has the specified name.
logger = MLogger.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 = MLogger.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 = MLogger.new(['foo.log', {age: 10, size: 1024000}])
-
Create a logger which ages logfile daily/weekly/monthly.
logger = MLogger.new(['foo.log', {age: 'daily'}]) logger = MLogger.new(['foo.log', {age: 'weekly'}]) logger = MLogger.new(['foo.log', {age: 'monthly'}])
-
Create a logger with multiIO
logger = MLogger.new STDOUT, STDERR logger = MLogger.new ['foo.log', {age: 'daily'}], ['foo2.log', {age: 'weekly'}] logger = MLogger.new STDOUT, 'foo.log' logger = MLogger.new STDOUT, ['foo.log', {age: 'daily'}]
-
Create a logger with different log levels with different IO.
logger = MLogger.new STDOUT # default io logger.change_level_logdev MLogger::WARN, STDERR logger.change_level_logdev [:warn, :error], STDERR
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 block.
logger.fatal { "Argument 'foo' not given." }
-
Message as a string.
logger.error "Argument #{ @foo } mismatch."
-
With progname.
logger.info('initialize') { "Initializing..." }
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 = MLogger::WARN
-
Log4r (somewhat) compatible interface.
logger.level = MLogger::INFO DEBUG < INFO < WARN < ERROR < FATAL
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, [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 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 with formatter=
method.
logger.formatter = proc do |severity, datetime, progname, msg| "#{datetime}: #{msg}\n" end # e.g. "Thu Sep 22 08:51:08 GMT+9:00 2005: hello world"
Constants
- LOGGER_LEVEL
When you set +$LOGGER_LEVEL+ before require mlogger, you can define yourself log level like default value [:DEBUG, :INFO, :WARN, :ERROR, :FATAL] DEBUG < INFO < WARN < ERROR < FATAL
- VERSION
Attributes
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.
Logging severity threshold (e.g. Logger::INFO
).
program name to include in log messages.
Logging severity threshold (e.g. Logger::INFO
).
Logging severity threshold (e.g. Logger::INFO
).
Public Class Methods
Synopsis¶ ↑
MLogger.new(+logdev+) MLogger.new([name, {age: 7, size: 1048576}]) MLogger.new([name, {age: 'weekly'}]) MLogger.new([+logdev+, {age: +shift_age+, size: +shift_size+}])
Args¶ ↑
Every Arg is a logdev information:
logdev
-
The log device. Array 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.
# File lib/mlogger.rb, line 301 def initialize(*logdev) @progname = nil @level = 0 @default_formatter = Formatter.new @formatter = nil logdev << STDOUT if logdev.empty? @logdev = LogDeveices.new(*logdev) @level_logdev = {} end
Public Instance Methods
Dump given message to the log device without any formatting. If no log device exists, return nil
.
# File lib/mlogger.rb, line 352 def <<(msg) unless @logdev.nil? @logdev.write(msg) end end
Synopsis¶ ↑
Logger#change_level_logdev(levels, *logdev)
Use¶ ↑
logger.change_level_logdev :warn, STDERR logger.change_level_logdev [:warn, :error], STDERR logger.change_level_logdev MLogger::WARN..MLogger::FATAL, STDERR
Args¶ ↑
levels
-
Severity. Constants are defined in Logger namespace:
DEBUG
,INFO
,WARN
,ERROR
,FATAL
. Also can use a Severity Array. 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¶ ↑
Change LEVEL LogDev
# File lib/mlogger.rb, line 340 def change_level_logdev(levels, *logdev) levels = [levels] unless levels.is_a? Enumerable log_deveices = LogDeveices.new(*logdev) levels.each do |level| @level_logdev[trans_level level] = log_deveices end end
Close the logging device.
# File lib/mlogger.rb, line 361 def close @logdev.close if @logdev @level_logdev.values.each {|logdev| logdev.close if logdev} end
Returns the date format being used. See datetime_format=
# File lib/mlogger.rb, line 257 def datetime_format @default_formatter.datetime_format end
Set date-time format.
datetime_format
-
A string suitable for passing to
strftime
.
# File lib/mlogger.rb, line 252 def datetime_format=(datetime_format) @default_formatter.datetime_format = datetime_format end
Private Instance Methods
Synopsis¶ ↑
MLogger#add(severity, message = nil, progname = nil) { ... }
Args¶ ↑
severity
-
Severity. Constants are defined in Logger namespace:
DEBUG
,INFO
,WARN
,ERROR
,FATAL
. 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¶ ↑
true
if successful, false
otherwise.
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 which supports multi I/O, records possibly be mixed.
# File lib/mlogger.rb, line 425 def add(severity, message = nil, progname = nil, &block) 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 (@level_logdev[severity] || @logdev).write( format_message(format_severity(severity), Time.now, progname, message)) true end
# File lib/mlogger.rb, line 377 def format_message(severity, datetime, progname, msg) (@formatter || @default_formatter).call(severity, datetime, progname, msg) end
# File lib/mlogger.rb, line 373 def format_severity(severity) LOGGER_LEVEL[severity] || 'ANY' end
# File lib/mlogger.rb, line 368 def trans_level(level) (level.is_a? String or level.is_a? Symbol) ? MLogger.const_get(level.upcase) : level end