Module: Logging::Appenders::Buffering

### Home Classes Methods

### In Files

- lib/logging/appenders/buffering.rb

### Namespace

- CLASS Logging::Appenders::Buffering::PeriodicFlusher

### Methods

- ::new
- #auto_flushing=
- #clear!
- #close
- #configure_buffering
- #flush
- #flush_period=
- #immediate?
- #immediate_at=
- #reopen

### Files

- History.txt

### Class/Module Index

Quicksearch

- Logging
- Logging::Appender
- Logging::Appenders
- Logging::Appenders::Buffering
- Logging::Appenders::File
- Logging::Appenders::IO
- Logging::Appenders::RollingFile
- Logging::Appenders::RollingFile::Roller
- Logging::Appenders::Stderr
- Logging::Appenders::Stdout
- Logging::Appenders::StringIo
- Logging::Appenders::Syslog
- Logging::ColorScheme
- Logging::Filter
- Logging::Filters
- Logging::Filters::Level
- Logging::Layout
- Logging::Layouts
- Logging::Layouts::Basic
- Logging::Layouts::Parseable
- Logging::Layouts::Pattern
- Logging::Logger
- Logging::MappedDiagnosticContext
- Logging::NestedDiagnosticContext
- Logging::Proxy
- Logging::RailsCompat
- Logging::Repository
- Logging::Repository::Singleton
- Logging::RootLogger
- RSpec
- RSpec::Core
- RSpec::Core::Configuration
- RSpec::LoggingHelper
- RSpec::LoggingHelper
- Spec
- Spec::Runner
- Spec::Runner::Configuration
- Object
- Object::LoggingHelper
- File
- FileUtils
- Module
- ReentrantMutex
- String

No matching classes.

# Logging::Appenders::Buffering

The Buffering module is used to implement buffering of the log messages in a given appender. The size of the buffer can be specified, and the buffer can be configured to auto-flush at a given threshold. The threshold can be a single message or a very large number of messages.

Log messages of a certain level can cause the buffer to be flushed immediately. If an error occurs, all previous messages and the error message will be written immediately to the logging destination if the buffer is configured to do so.

### Constants

DEFAULT_BUFFER_SIZE

  Default buffer size

### Attributes

auto_flushing[R]

The auto-flushing setting. When the buffer reaches this size, all messages will be be flushed automatically.

buffer[R]

The buffer holding the log messages

flush_period[R]

When set, the buffer will be flushed at regular intervals defined by the flush_period.

write_size[RW]

Messages will be written in chunks. This controls the number of messages to pull from the buffer for each write operation. The default is to pull all messages from the buffer at once.

### Public Class Methods

new( *args, &block ) click to toggle source

Setup the message buffer and other variables for automatically and periodically flushing the buffer.

    # File lib/logging/appenders/buffering.rb, line 38
    def initialize( *args, &block )
      @buffer = []
      @immediate = []
      @auto_flushing = 1
      @flush_period = @periodic_flusher = nil

      super(*args, &block)
    end

### Public Instance Methods

auto_flushing=( period ) click to toggle source

Configure the auto-flushing threshold. Auto-flushing is used to flush the contents of the logging buffer to the logging destination automatically when the buffer reaches a certain threshold.

By default, the auto-flushing will be configured to flush after each log message.

The allowed settings are as follows:

    N      : flush after every N messages (N is an integer)
    true   : flush after each log message
    false  OR
    nil    OR
    0      : only flush when the buffer is full (500 messages)

If the default buffer size of 500 is too small, then you can manually configure it to be as large as you want. This will consume more memory.

    auto_flushing = 42_000

    # File lib/logging/appenders/buffering.rb, line 155
    def auto_flushing=( period )
      @auto_flushing =
        case period
        when true;             1
        when false, nil, 0;    DEFAULT_BUFFER_SIZE
        when Integer;          period
        when String;           Integer(period)
        else
          raise ArgumentError,
                "unrecognized auto_flushing period: #{period.inspect}"
        end

      if @auto_flushing <= 0
        raise ArgumentError,
          "auto_flushing period must be greater than zero: #{period.inspect}"
      end

      @auto_flushing = DEFAULT_BUFFER_SIZE if @flush_period && @auto_flushing <= 1
    end

clear!() click to toggle source

Clear the underlying buffer of all log events. These events will not be appended to the logging destination; they will be lost.

    # File lib/logging/appenders/buffering.rb, line 97
    def clear!
      sync { @buffer.clear }
    end

close( *args ) click to toggle source

Close the message buffer by flushing all log events to the appender. If a periodic flusher thread is running, shut it down and allow it to exit.

    # File lib/logging/appenders/buffering.rb, line 50
    def close( *args )
      flush

      if @periodic_flusher
        @periodic_flusher.stop
        @periodic_flusher = nil
        Thread.pass
      end

      super(*args)
    end

flush() click to toggle source

Call `flush` to force an appender to write out any buffered log events. Similar to `IO#flush`, so use in a similar fashion.

    # File lib/logging/appenders/buffering.rb, line 73
    def flush
      return self if @buffer.empty?

      ary = nil
      sync {
        ary = @buffer.dup
        @buffer.clear
      }

      if ary.length <= write_size
        str = ary.join
        canonical_write str unless str.empty?
      else
        ary.each_slice(write_size) do |a|
          str = a.join
          canonical_write str unless str.empty?
        end
      end

      self
    end

flush_period=( period ) click to toggle source

Configure periodic flushing of the message buffer. Periodic flushing is used to flush the contents of the logging buffer at some regular interval. Periodic flushing is disabled by default.

When enabling periodic flushing the flush period should be set using one of the following formats: "HH:MM:SS" or seconds as an numeric or string.

    "01:00:00"  : every hour
    "00:05:00"  : every 5 minutes
    "00:00:30"  : every 30 seconds
    60          : every 60 seconds (1 minute)
    "120"       : every 120 seconds (2 minutes)

For the periodic flusher to work properly, the auto-flushing threshold will be set to the default value of 500. The auto-flushing threshold can be changed, but it must be greater than 1.

To disable the periodic flusher simply set the flush period to `nil`. The auto-flushing threshold will not be changed; it must be disabled manually if so desired.

    # File lib/logging/appenders/buffering.rb, line 196
    def flush_period=( period )
      period =
        case period
        when Integer, Float, nil; period
        when String;
          num = _parse_hours_minutes_seconds(period) || _parse_numeric(period)
          num = ArgumentError.new("unrecognized flush period: #{period.inspect}") if num.nil?
          num
        else ArgumentError.new("unrecognized flush period: #{period.inspect}") end

      raise period if Exception === period
      @flush_period = period

      _setup_periodic_flusher
    end

immediate_at=( level ) click to toggle source

Configure the levels that will trigger an immediate flush of the logging buffer. When a log event of the given level is seen, the buffer will be flushed immediately. Only the levels explicitly given in this assignment will flush the buffer; if an "error" message is configured to immediately flush the buffer, a "fatal" message will not even though it is a higher level. Both must be explicitly passed to this assignment.

You can pass in a single level name or number, an array of level names or numbers, or a string containing a comma separated list of level names or numbers.

    immediate_at = :error
    immediate_at = [:error, :fatal]
    immediate_at = "warn, error"

    # File lib/logging/appenders/buffering.rb, line 117
    def immediate_at=( level )
      @immediate.clear

      # get the immediate levels -- no buffering occurs at these levels, and
      # a log message is written to the logging destination immediately
      immediate_at =
        case level
        when String; level.split(',').map {|x| x.strip}
        when Array; level
        else Array(level) end

      immediate_at.each do |lvl|
        num = ::Logging.level_num(lvl)
        next if num.nil?
        @immediate[num] = true
      end
    end

reopen() click to toggle source

Reopen the connection to the underlying logging destination. In addition if the appender is configured for periodic flushing, then the flushing thread will be stopped and restarted.

    # File lib/logging/appenders/buffering.rb, line 66
    def reopen
      _setup_periodic_flusher
      super
    end

### Protected Instance Methods

configure_buffering( opts ) click to toggle source

Configure the buffering using the arguments found in the give options hash. This method must be called in order to use the message buffer. The supported options are "immediate_at" and "auto_flushing". Please refer to the documentation for those methods to see the allowed options.

    # File lib/logging/appenders/buffering.rb, line 220
    def configure_buffering( opts )
      ::Logging.init unless ::Logging.initialized?

      self.immediate_at  = opts.fetch(:immediate_at, '')
      self.auto_flushing = opts.fetch(:auto_flushing, true)
      self.flush_period  = opts.fetch(:flush_period, nil)
      self.write_size    = opts.fetch(:write_size, DEFAULT_BUFFER_SIZE)
    end

immediate?( event ) click to toggle source

Returns true if the event level matches one of the configured immediate logging levels. Otherwise returns false.

    # File lib/logging/appenders/buffering.rb, line 232
    def immediate?( event )
      return false unless event.respond_to? :level
      @immediate[event.level]
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.