Class: MLogger

Inherits:

Object

Object
MLogger

show all

Defined in:: lib/mlogger.rb,
lib/mlogger/version.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 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"

Defined Under Namespace

Classes: Error, Formatter, LogDeveices, ShiftingError

Constant Summary collapse

ProgName = :nodoc:

"#{File.basename(__FILE__)}/#{VERSION}"

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

($LOGGER_LEVEL ||
    [:DEBUG, :INFO, :WARN, :ERROR, :FATAL]).map.with_index do |level, index|

  level_upcase, level_downcase = level.upcase, level.downcase
  const_set level_upcase, index
  define_method "#{level_downcase}" do |progname = nil, &block|
    add(index, nil, progname, &block)
  end
  define_method "#{level_downcase}?" do
    @level <= index
  end

  level_upcase.to_sym
end

VERSION =

"1.0.4"

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.
#change_level_logdev(levels, *logdev) ⇒ Object

Synopsis.
#close ⇒ Object

Close the logging device.
#datetime_format ⇒ Object

Returns the date format being used.
#datetime_format=(datetime_format) ⇒ Object

Set date-time format.
#initialize(*logdev) ⇒ MLogger constructor

Synopsis.

Constructor Details

#initialize(*logdev) ⇒ `MLogger`

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 or monthly).
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

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.



271
272
273

# File 'lib/mlogger.rb', line 271

def formatter
  @formatter
end

#level ⇒ `Object` Also known as: sev_threshold

Logging severity threshold (e.g. Logger::INFO).



240
241
242

# File 'lib/mlogger.rb', line 240

def level
  @level
end

#progname ⇒ `Object`

program name to include in log messages.



247
248
249

# File 'lib/mlogger.rb', line 247

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.

# File 'lib/mlogger.rb', line 352

def <<(msg)
  unless @logdev.nil?
    @logdev.write(msg)
  end
end

#change_level_logdev(levels, *logdev) ⇒ `Object`

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 or monthly).
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 ⇒ `Object`

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

#datetime_format ⇒ `Object`

Returns the date format being used. See #datetime_format=



257
258
259

# File 'lib/mlogger.rb', line 257

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.



252
253
254

# File 'lib/mlogger.rb', line 252

def datetime_format=(datetime_format)
  @default_formatter.datetime_format = datetime_format
end

Class: MLogger

Overview

Description

Example

Features

HOWTOs

How to create a logger

How to log a message

How to close a logger

Setting severity threshold

Format

Defined Under Namespace

Constant Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Synopsis.

Synopsis.

Constructor Details

#initialize(*logdev) ⇒ MLogger

Synopsis

Args

Description

Instance Attribute Details

#formatter ⇒ Object

#level ⇒ Object Also known as: sev_threshold

#progname ⇒ Object

Instance Method Details

#<<(msg) ⇒ Object

#change_level_logdev(levels, *logdev) ⇒ Object

Synopsis

Use

Args

Description

#close ⇒ Object

#datetime_format ⇒ Object

#datetime_format=(datetime_format) ⇒ Object

#initialize(*logdev) ⇒ `MLogger`

#formatter ⇒ `Object`

#level ⇒ `Object` Also known as: sev_threshold

#progname ⇒ `Object`

#<<(msg) ⇒ `Object`

#change_level_logdev(levels, *logdev) ⇒ `Object`

#close ⇒ `Object`

#datetime_format ⇒ `Object`

#datetime_format=(datetime_format) ⇒ `Object`