Class: Logger

Inherits:
Object
  • Object
show all
Includes:
Severity
Defined in:
lib/logger.rb,
lib/logger/errors.rb,
lib/logger/period.rb,
lib/logger/version.rb,
lib/logger/severity.rb,
lib/logger/formatter.rb,
lib/logger/log_device.rb

Overview

not used after 1.2.7. just for compat.

Defined Under Namespace

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

Constant Summary collapse

ProgName = 
"#{name}/#{rev}"
VERSION = 
"1.4.3"

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

#initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG, progname: nil, formatter: nil, datetime_format: nil, binmode: false, shift_period_suffix: '%Y%m%d') ⇒ Logger

:call-seq:

Logger.new(logdev, shift_age = 0, shift_size = 1048576)
Logger.new(logdev, shift_age = 'weekly')
Logger.new(logdev, level: :info)
Logger.new(logdev, progname: 'progname')
Logger.new(logdev, formatter: formatter)
Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')

Args

logdev

The log device. This is a filename (String), IO object (typically STDOUT, STDERR, or an open file), nil (it writes nothing) or File::NULL (same as nil).

shift_age

Number of old log files to keep, or frequency of rotation (daily, weekly or monthly). Default value is 0, which disables log file rotation.

shift_size

Maximum logfile size in bytes (only applies when shift_age is a positive Integer). Defaults to 1048576 (1MB).

level

Logging severity threshold. Default values is Logger::DEBUG.

progname

Program name to include in log messages. Default value is nil.

formatter

Logging formatter. Default values is an instance of Logger::Formatter.

datetime_format

Date and time format. Default value is ‘%Y-%m-%d %H:%M:%S’.

binmode

Use binary mode on the log device. Default value is false.

shift_period_suffix

The log file suffix format for daily, weekly or monthly rotation. Default is ‘%Y%m%d’.

Description

Create an instance.



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/logger.rb', line 380

def initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG,
               progname: nil, formatter: nil, datetime_format: nil,
               binmode: false, shift_period_suffix: '%Y%m%d')
  self.level = level
  self.progname = progname
  @default_formatter = Formatter.new
  self.datetime_format = datetime_format
  self.formatter = formatter
  @logdev = nil
  if logdev && logdev != File::NULL
    @logdev = LogDevice.new(logdev, shift_age: shift_age,
      shift_size: shift_size,
      shift_period_suffix: shift_period_suffix,
      binmode: binmode)
  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.



300
301
302
 
# File 'lib/logger.rb', line 300

def formatter
  @formatter
end

#level ⇒ Object Also known as: sev_threshold

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



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

def level
  @level
end

#progname ⇒ Object

Program name to include in log messages.



274
275
276
 
# File 'lib/logger.rb', line 274

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.



485
486
487
 
# File 'lib/logger.rb', line 485

def <<(msg)
  @logdev&.write(msg)
end

#add(severity, message = nil, progname = nil) ⇒ 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, 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

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.



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/logger.rb', line 459

def add(severity, message = nil, progname = nil)
  severity ||= UNKNOWN
  if @logdev.nil? or severity < level
    return true
  end
  if progname.nil?
    progname = @progname
  end
  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

#close ⇒ Object

Close the logging device.



572
573
574
 
# File 'lib/logger.rb', line 572

def close
  @logdev&.close
end

#datetime_format ⇒ Object

Returns the date format being used. See #datetime_format=



284
285
286
 
# File 'lib/logger.rb', line 284

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.



279
280
281
 
# File 'lib/logger.rb', line 279

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.



494
495
496
 
# File 'lib/logger.rb', line 494

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

#debug! ⇒ Object

Sets the severity to DEBUG.



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

def debug!; self.level = DEBUG; end

#debug? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def debug?; level <= DEBUG; end

#error(progname = nil, &block) ⇒ Object

Log an ERROR message.

See #info for more information.



546
547
548
 
# File 'lib/logger.rb', line 546

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

#error! ⇒ Object

Sets the severity to ERROR.



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

def error!; self.level = ERROR; end

#error? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def error?; level <= ERROR; end

#fatal(progname = nil, &block) ⇒ Object

Log a FATAL message.

See #info for more information.



555
556
557
 
# File 'lib/logger.rb', line 555

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

#fatal! ⇒ Object

Sets the severity to FATAL.



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

def fatal!; self.level = FATAL; end

#fatal? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def fatal?; level <= FATAL; end

#info(progname = nil, &block) ⇒ Object

:call-seq:

info(message)
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.



528
529
530
 
# File 'lib/logger.rb', line 528

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

#info! ⇒ Object

Sets the severity to INFO.



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

def info!; self.level = INFO; end

#info? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def info?; level <= INFO; end

#reopen(logdev = nil) ⇒ Object

:call-seq:

Logger#reopen
Logger#reopen(logdev)

Args

logdev

The log device. This is a filename (String) or IO object (typically STDOUT, STDERR, or an open file). reopen the same filename if it is nil, do nothing for IO. Default is nil.

Description

Reopen a log device.



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

def reopen(logdev = nil)
  @logdev&.reopen(logdev)
  self
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.



565
566
567
 
# File 'lib/logger.rb', line 565

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.



537
538
539
 
# File 'lib/logger.rb', line 537

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

#warn! ⇒ Object

Sets the severity to WARN.



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

def warn!; self.level = WARN; end

#warn? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def warn?; level <= WARN; end