# Logger (Class)

In: | logger.rb
Parent: | Object

DESCRIPTION

      Logger -- Logging utility.

How to create a logger.

      1. Create logger which logs messages to STDERR/STDOUT.
        logger = Logger.new(STDERR)
        logger = Logger.new(STDOUT)

      2. Create logger for the file which has the specified name.
        logger = Logger.new('logfile.log')

      3. Create logger for the specified 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 = Logger.new(file)

      4. Create logger which ages logfile automatically.  Leave 10 ages and each
         file is about 102400 bytes.
        logger = Logger.new('foo.log', 10, 102400)

      5. Create logger which ages logfile daily/weekly/monthly automatically.
        logger = Logger.new('foo.log', 'daily')
        logger = Logger.new('foo.log', 'weekly')
        logger = Logger.new('foo.log', 'monthly')

How to log a message.

      1. Message in block.
        logger.fatal { "Argument 'foo' not given." }

      2. Message as a string.
        logger.error "Argument #{ @foo } mismatch."

      3. With progname.
        logger.info('initialize') { "Initializing..." }

      4. With severity.
        logger.add(Logger::FATAL) { 'Fatal error!' }

How to close a logger.

      logger.close

Setting severity threshold.

      1. Original interface.
        logger.level = Logger::WARN

      2. Log4r (somewhat) compatible interface.
        logger.level = Logger::INFO

      DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN

Format.

      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.

## Methods

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

## Constants

ProgName | = | "#{$1}/#{$2}"
SEV_LABEL | = | %w(DEBUG INFO WARN ERROR FATAL ANY);
| Severity label for logging. (max 5 char)
Format | = | "%s, [%s#%d] %5s -- %s: %s\n"

## External Aliases

level -> sev_threshold
level= -> sev_threshold=

## Attributes

datetime_format | [RW] | Logging date-time format (string passed to strftime)
level | [RW] | Logging severity threshold.
progname | [RW] | Logging program name.

## Classes and Modules

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

## Included Modules

Severity

## Public Class methods

new(logdev, shift_age = 0, shift_size = 1048576)

SYNOPSIS

      Logger.new(name, shift_age = 7, shift_size = 1048576)

ARGS

      log       String as filename of logging.
                or
                IO as logging device(i.e. STDERR).
      shift_age An Integer      Num of files you want to keep aged logs.
                'daily'            Daily shifting.
                'weekly'   Weekly shifting (Every monday.)
                'monthly'  Monthly shifting (Every 1th day.)
      shift_size        Shift size threshold when shift_age is an integer.
                Otherwise (like 'daily'), shift_size will be ignored.

DESCRIPTION

      Create an instance.

[Source]

    # File logger.rb, line 126
      def initialize(logdev, shift_age = 0, shift_size = 1048576)
        @logdev = nil
        @progname = nil
        @level = DEBUG
        @datetime_format = nil
        @logdev = nil
        if logdev
          @logdev = LogDevice.new(logdev, :shift_age => shift_age, :shift_size => shift_size)
        end
      end

## Public Instance methods

debug?()

[Source]

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

info?()

[Source]

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

warn?()

[Source]

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

error?()

[Source]

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

fatal?()

[Source]

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

add(severity, msg = nil, progname = nil, &block) {|| ...}

SYNOPSIS

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

ARGS

      severity  Severity.  Constants are defined in Logger namespace.
                DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN.
      msg       Message.  A string, exception, or something. Can be omitted.
      progname  Program name string.  Can be omitted.
                Logged as a msg if no msg and block are given.
      block     Can be omitted.
                Called to get a message string if msg is nil.

RETURN

      true if succeed, false if failed.
      When the given severity is not enough severe,
      Log no message, and returns true.

DESCRIPTION

      Log a log if the given severity is enough severe.

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 162
      def add(severity, msg = nil, progname = nil, &block)
        severity ||= UNKNOWN
        if @logdev.nil? or severity < @level
          return true
        end
        progname ||= @progname
        if msg.nil?
          if block_given?
            msg = yield
          else
            msg = progname
            progname = @progname
          end
        end
        @logdev.write(
          format_message(
            format_severity(severity),
            format_datetime(Time.now),
            msg2str(msg),
            progname
          )
        )
        true
      end

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

Alias for add

<<(msg)

SYNOPSIS

      Logger#<<(msg)

ARGS

      msg       Message.

RETURN

      Same as IO#<<.  If logdev is not given, returns nil.

DESCRIPTION

      Dump given message to log device without any formatting.

[Source]

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

debug(progname = nil, &block)

SYNOPSIS

      Logger#debug(progname = nil) { ... } = nil
      Logger#info(progname = nil) { ... } = nil
      Logger#warn(progname = nil) { ... } = nil
      Logger#error(progname = nil) { ... } = nil
      Logger#fatal(progname = nil) { ... } = nil
      Logger#unknown(progname = nil) { ... } = nil

ARGS

      progname  Program name string.  Can be omitted.
                Logged as a msg if no block are given.
      block     Can be omitted.
                Called to get a message string if msg is nil.

RETURN

      See Logger#add .

DESCRIPTION

      Log a log.

[Source]

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

info(progname = nil, &block)

[Source]

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

warn(progname = nil, &block)

[Source]

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

error(progname = nil, &block)

[Source]

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

fatal(progname = nil, &block)

[Source]

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

unknown(progname = nil, &block)

[Source]

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

close()

SYNOPSIS

      Logger#close

DESCRIPTION

      Close the logging device.

[Source]

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

[Validate]