Class: Logger

Inherits:
Object show all
Includes:
Severity
Defined in:
lib/logger.rb

Defined Under Namespace

Modules: Severity Classes: Application, Error, Formatter, LogDevice, ShiftingError

Constant Summary

VERSION = 
"1.2.7"
ProgName = 
"#{name}/#{rev}"
SEV_LABEL =

Severity label for logging. (max 5 char)

%w(DEBUG INFO WARN ERROR FATAL ANY)

Constants included from Severity

Severity::DEBUG, Severity::ERROR, Severity::FATAL, Severity::INFO, Severity::UNKNOWN, Severity::WARN

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Logger) initialize(logdev, shift_age = 0, shift_size = 1048576)

Synopsis

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

shift_size

Maximum logfile size (only applies when shift_age is a number).

Description

Create an instance.



268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/logger.rb', line 268

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

- (Object) formatter

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.



222
223
224
 
# File 'lib/logger.rb', line 222

def formatter
  @formatter
end

- (Object) level Also known as: sev_threshold

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



203
204
205
 
# File 'lib/logger.rb', line 203

def level
  @level
end

- (Object) progname

Logging program name.



206
207
208
 
# File 'lib/logger.rb', line 206

def progname
  @progname
end

Instance Method Details

- (Object) <<(msg)

Dump given message to the log device without any formatting. If no log device exists, return nil.



348
349
350
351
352
 
# File 'lib/logger.rb', line 348

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

- (Object) add(severity, message = nil, progname = nil, &block) Also known as: log

Synopsis

Logger#add(severity, message = nil, progname = nil) { ... }

Args

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.

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.

  • But on the OS which supports multi I/O, records possibly be mixed.



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/logger.rb', line 324

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

- (Object) close

Close the logging device.



429
430
431
 
# File 'lib/logger.rb', line 429

def close
  @logdev.close if @logdev
end

- (Object) datetime_format 



213
214
215
 
# File 'lib/logger.rb', line 213

def datetime_format
  @default_formatter.datetime_format
end

- (Object) datetime_format=(datetime_format)

Logging date-time format (string passed to strftime).



209
210
211
 
# File 'lib/logger.rb', line 209

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

- (Object) debug(progname = nil, &block)

Log a DEBUG message.

See #info for more information.



359
360
361
 
# File 'lib/logger.rb', line 359

def debug(progname = nil, &block)
  add(DEBUG, nil, progname, &block)
end

- (Boolean) debug?

Returns true iff the current severity level allows for the printing of DEBUG messages.

Returns:

  • (Boolean) 


229
 
# File 'lib/logger.rb', line 229

def debug?; @level <= DEBUG; end

- (Object) error(progname = nil, &block)

Log an ERROR message.

See #info for more information.



403
404
405
 
# File 'lib/logger.rb', line 403

def error(progname = nil, &block)
  add(ERROR, nil, progname, &block)
end

- (Boolean) error?

Returns true iff the current severity level allows for the printing of ERROR messages.

Returns:

  • (Boolean) 


241
 
# File 'lib/logger.rb', line 241

def error?; @level <= ERROR; end

- (Object) fatal(progname = nil, &block)

Log a FATAL message.

See #info for more information.



412
413
414
 
# File 'lib/logger.rb', line 412

def fatal(progname = nil, &block)
  add(FATAL, nil, progname, &block)
end

- (Boolean) fatal?

Returns true iff the current severity level allows for the printing of FATAL messages.

Returns:

  • (Boolean) 


245
 
# File 'lib/logger.rb', line 245

def fatal?; @level <= FATAL; end

- (Object) info(progname = nil, &block)

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.

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 Logger#progname= as well).

Return

See #add.



385
386
387
 
# File 'lib/logger.rb', line 385

def info(progname = nil, &block)
  add(INFO, nil, progname, &block)
end

- (Boolean) info?

Returns true iff the current severity level allows for the printing of INFO messages.

Returns:

  • (Boolean) 


233
 
# File 'lib/logger.rb', line 233

def info?; @level <= INFO; end

- (Object) unknown(progname = nil, &block)

Log an UNKNOWN message. This will be printed no matter what the logger level.

See #info for more information.



422
423
424
 
# File 'lib/logger.rb', line 422

def unknown(progname = nil, &block)
  add(UNKNOWN, nil, progname, &block)
end

- (Object) warn(progname = nil, &block)

Log a WARN message.

See #info for more information.



394
395
396
 
# File 'lib/logger.rb', line 394

def warn(progname = nil, &block)
  add(WARN, nil, progname, &block)
end

- (Boolean) warn?

Returns true iff the current severity level allows for the printing of WARN messages.

Returns:

  • (Boolean) 


237
 
# File 'lib/logger.rb', line 237

def warn?; @level <= WARN; end