Class: Logger

Class | Logger
In: | logger.rb
Parent: | Object

### Methods

<< add close datetime_format datetime_format= debug debug? error error? fatal fatal? info info? log new unknown warn warn?

### Included Modules

Severity

### Classes and Modules

Module Logger::Severity
Class Logger::Application
Class Logger::Error
Class Logger::Formatter
Class Logger::LogDevice
Class Logger::ShiftingError

### Constants

VERSION | = | "1.2.6"
ProgName | = | "#{$1}/#{$2}"
SEV_LABEL | = | %w(DEBUG INFO WARN ERROR FATAL ANY) |  | Severity label for logging. (max 5 char)

### External Aliases

level | -> | sev_threshold
level= | -> | sev_threshold=

### Attributes

formatter | [RW] | Logging formatter. formattercall 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 logdevwrite-able Object. Default formatter is used when no formatter is set.
level | [RW] | Logging severity threshold (e.g. `Logger::INFO`).
progname | [RW] | Logging program name.

### Public Class methods

new(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.

[Source]

    # File logger.rb, line 265
      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

### Public Instance methods

<<(msg)

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

[Source]

    # File logger.rb, line 345
      def <<(msg)
        unless @logdev.nil?
          @logdev.write(msg)
        end
      end

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

### 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.

[Source]

    # File logger.rb, line 321
      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

close()

Close the logging device.

[Source]

    # File logger.rb, line 426
      def close
        @logdev.close if @logdev
      end

datetime_format()

[Source]

    # File logger.rb, line 210
      def datetime_format
        @default_formatter.datetime_format
      end

datetime_format=(datetime_format)

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

[Source]

    # File logger.rb, line 206
      def datetime_format=(datetime_format)
        @default_formatter.datetime_format = datetime_format
      end

debug(progname = nil, &block)

Log a `DEBUG` message.

See info for more information.

[Source]

    # File logger.rb, line 356
      def debug(progname = nil, &block)
        add(DEBUG, nil, progname, &block)
      end

debug?()

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

[Source]

    # File logger.rb, line 226
      def debug?; @level <= DEBUG; end

error(progname = nil, &block)

Log an `ERROR` message.

See info for more information.

[Source]

    # File logger.rb, line 400
      def error(progname = nil, &block)
        add(ERROR, nil, progname, &block)
      end

error?()

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

[Source]

    # File logger.rb, line 238
      def error?; @level <= ERROR; end

fatal(progname = nil, &block)

Log a `FATAL` message.

See info for more information.

[Source]

    # File logger.rb, line 409
      def fatal(progname = nil, &block)
        add(FATAL, nil, progname, &block)
      end

fatal?()

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

[Source]

    # File logger.rb, line 242
      def fatal?; @level <= FATAL; end

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.

[Source]

    # File logger.rb, line 382
      def info(progname = nil, &block)
        add(INFO, nil, progname, &block)
      end

info?()

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

[Source]

    # File logger.rb, line 230
      def info?; @level <= INFO; end

log(severity, message = nil, progname = nil, &block)

Alias for add

unknown(progname = nil, &block)

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

See info for more information.

[Source]

    # File logger.rb, line 419
      def unknown(progname = nil, &block)
        add(UNKNOWN, nil, progname, &block)
      end

warn(progname = nil, &block)

Log a `WARN` message.

See info for more information.

[Source]

    # File logger.rb, line 391
      def warn(progname = nil, &block)
        add(WARN, nil, progname, &block)
      end

warn?()

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

[Source]

    # File logger.rb, line 234
      def warn?; @level <= WARN; end

[Validate]