Module: Logging::Appenders::Buffering

Included in:
Email, IO
Defined in:
lib/logging/appenders/buffering.rb

Overview

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.

Defined Under Namespace

Classes: PeriodicFlusher

Constant Summary collapse

DEFAULT_BUFFER_SIZE =

Default buffer size

500

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#auto_flushing ⇒ Object

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



27
28
29
 
# File 'lib/logging/appenders/buffering.rb', line 27

def auto_flushing
  @auto_flushing
end

#buffer ⇒ Object (readonly)

The buffer holding the log messages



22
23
24
 
# File 'lib/logging/appenders/buffering.rb', line 22

def buffer
  @buffer
end

#flush_period ⇒ Object

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



32
33
34
 
# File 'lib/logging/appenders/buffering.rb', line 32

def flush_period
  @flush_period
end

Instance Method Details

#close(*args) ⇒ Object

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.



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/logging/appenders/buffering.rb', line 49

def close( *args )
  flush

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

  super(*args)
end

#flush ⇒ Object

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



73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/logging/appenders/buffering.rb', line 73

def flush
  return self if @buffer.empty?

  str = nil
  sync {
    str = @buffer.join
    @buffer.clear
  }

  canonical_write str unless str.empty?
  self
end

#immediate_at=(level) ⇒ Object

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"



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/logging/appenders/buffering.rb', line 102

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

#initialize(*args, &block) ⇒ Object

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



37
38
39
40
41
42
43
44
 
# File 'lib/logging/appenders/buffering.rb', line 37

def initialize( *args, &block )
  @buffer = []
  @immediate = []
  @auto_flushing = 1
  @flush_period = @periodic_flusher = nil

  super(*args, &block)
end

#reopen ⇒ Object

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.



65
66
67
68
 
# File 'lib/logging/appenders/buffering.rb', line 65

def reopen
  _setup_periodic_flusher
  super
end