Class: Logging::Appender
- Inherits:
-
Object
- Object
- Logging::Appender
- Defined in:
- lib/logging/appender.rb
Overview
The Appender
class is provides methods for appending log events to a logging destination. The log events are formatted into strings using a Layout.
All other Appenders inherit from this class which provides stub methods. Each subclass should provide a write
method that will write log messages to the logging destination.
A private sync
method is provided for use by subclasses. It is used to synchronize writes to the logging destination, and can be used by subclasses to synchronize the closing or flushing of the logging destination.
Direct Known Subclasses
Instance Attribute Summary collapse
-
#filters ⇒ Object
Returns the value of attribute filters.
-
#layout ⇒ Object
Returns the value of attribute layout.
-
#level ⇒ Object
Returns the value of attribute level.
-
#name ⇒ Object
readonly
Returns the value of attribute name.
Instance Method Summary collapse
-
#<<(str) ⇒ Object
call-seq: appender << string.
-
#_to_s ⇒ Object
Save off the original ‘to_s` for use in tests.
-
#add_filters(*args) ⇒ Object
Sets the filter(s) to be used by this appender.
-
#allow(event) ⇒ Object
Check to see if the event should be processed by the appender.
-
#append(event) ⇒ Object
call-seq: append( event ).
-
#close(footer = true) ⇒ Object
call-seq: close( footer = true ).
-
#closed? ⇒ Boolean
call-seq: closed?.
-
#encoding ⇒ Object
Returns the current Encoding for the appender or nil if an encoding has not been set.
-
#encoding=(value) ⇒ Object
Set the appender encoding to the given value.
-
#flush ⇒ Object
call-seq: flush.
-
#initialize(name, opts = {}) ⇒ Appender
constructor
call-seq: Appender.new( name ) Appender.new( name, :layout => layout ).
-
#off? ⇒ Boolean
Returns ‘true` if the appender has been turned off.
-
#reopen ⇒ Object
Reopen the connection to the underlying logging destination.
-
#to_s ⇒ Object
call-seq: to_s => string.
Constructor Details
#initialize(name, opts = {}) ⇒ Appender
call-seq:
Appender.new( name )
Appender.new( name, :layout => layout )
Creates a new appender using the given name. If no Layout is specified, then a Basic layout will be used. Any logging header supplied by the layout will be written to the logging destination when the Appender is created.
Options:
:layout => the layout to use when formatting log events
:level => the level at which to log
:encoding => encoding to use when writing messages (defaults to UTF-8)
:filters => filters to apply to events before processing
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 |
# File 'lib/logging/appender.rb', line 37 def initialize( name, opts = {} ) ::Logging.init unless ::Logging.initialized? @name = name.to_s @closed = false @filters = [] @mutex = ReentrantMutex.new self.layout = opts.fetch(:layout, ::Logging::Layouts::Basic.new) self.level = opts.fetch(:level, nil) self.encoding = opts.fetch(:encoding, self.encoding) self.filters = opts.fetch(:filters, nil) if opts.fetch(:header, true) header = @layout.header unless header.nil? || header.empty? begin write(header) rescue StandardError => err ::Logging.log_internal_error(err) end end end ::Logging::Appenders[@name] = self end |
Instance Attribute Details
#filters ⇒ Object
Returns the value of attribute filters.
19 20 21 |
# File 'lib/logging/appender.rb', line 19 def filters @filters end |
#layout ⇒ Object
Returns the value of attribute layout.
19 20 21 |
# File 'lib/logging/appender.rb', line 19 def layout @layout end |
#level ⇒ Object
Returns the value of attribute level.
19 20 21 |
# File 'lib/logging/appender.rb', line 19 def level @level end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
19 20 21 |
# File 'lib/logging/appender.rb', line 19 def name @name end |
Instance Method Details
#<<(str) ⇒ Object
call-seq:
appender << string
Write the given string to the logging destination “as is” – no layout formatting will be performed.
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 |
# File 'lib/logging/appender.rb', line 96 def <<( str ) if @closed raise RuntimeError, "appender '<#{self.class.name}: #{@name}>' is closed" end unless off? begin write(str) rescue StandardError => err ::Logging.log_internal_error(err) end end self end |
#_to_s ⇒ Object
Save off the original ‘to_s` for use in tests
255 |
# File 'lib/logging/appender.rb', line 255 alias_method :_to_s, :to_s |
#add_filters(*args) ⇒ Object
185 186 187 188 189 190 191 192 193 194 |
# File 'lib/logging/appender.rb', line 185 def add_filters( *args ) args.flatten.each do |filter| next if filter.nil? unless filter.kind_of?(::Logging::Filter) raise TypeError, "#{filter.inspect} is not a kind of 'Logging::Filter'" end @filters << filter end self end |
#allow(event) ⇒ Object
Check to see if the event should be processed by the appender. An event will be rejected if the event level is lower than the configured level for the appender. Or it will be rejected if one of the filters rejects the event.
event - The LogEvent to check
Returns the event if it is allowed; returns ‘nil` if it is not allowed.
298 299 300 301 302 303 304 |
# File 'lib/logging/appender.rb', line 298 def allow( event ) return nil if @level > event.level @filters.each do |filter| break unless event = filter.allow(event) end event end |
#append(event) ⇒ Object
call-seq:
append( event )
Write the given event to the logging destination. The log event will be processed through the Layout associated with the Appender.
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
# File 'lib/logging/appender.rb', line 71 def append( event ) if @closed raise RuntimeError, "appender '<#{self.class.name}: #{@name}>' is closed" end # only append if the event level is less than or equal to the configured # appender level and the filter does not disallow it if event = allow(event) begin write(event) rescue StandardError => err ::Logging.log_internal_error(err) end end self end |
#close(footer = true) ⇒ Object
call-seq:
close( = true )
Close the appender and writes the layout footer to the logging destination if the footer flag is set to true
. Log events will no longer be written to the logging destination after the appender is closed.
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 |
# File 'lib/logging/appender.rb', line 204 def close( = true ) return self if @closed ::Logging::Appenders.remove(@name) @closed = true flush if = @layout. unless .nil? || .empty? begin write() rescue StandardError => err ::Logging.log_internal_error(err) end end end self end |
#closed? ⇒ Boolean
call-seq:
closed?
Returns true
if the appender has been closed; returns false
otherwise. When an appender is closed, no more log events can be written to the logging destination.
231 232 233 |
# File 'lib/logging/appender.rb', line 231 def closed? @closed end |
#encoding ⇒ Object
Returns the current Encoding for the appender or nil if an encoding has not been set.
269 270 271 272 |
# File 'lib/logging/appender.rb', line 269 def encoding return @encoding if defined? @encoding @encoding = Object.const_defined?(:Encoding) ? Encoding.default_external : nil end |
#encoding=(value) ⇒ Object
Set the appender encoding to the given value. The value can either be an Encoding instance or a String or Symbol referring to a valid encoding.
This method only applies to Ruby 1.9 or later. The encoding will always be nil for older Rubies.
value - The encoding as a String, Symbol, or Encoding instance.
Raises ArgumentError if the value is not a valid encoding.
283 284 285 286 287 288 289 |
# File 'lib/logging/appender.rb', line 283 def encoding=( value ) if value.nil? @encoding = nil else @encoding = Object.const_defined?(:Encoding) ? Encoding.find(value.to_s) : nil end end |
#flush ⇒ Object
call-seq:
flush
Call flush
to force an appender to write out any buffered log events. Similar to IO#flush, so use in a similar fashion.
250 251 252 |
# File 'lib/logging/appender.rb', line 250 def flush self end |
#off? ⇒ Boolean
Returns ‘true` if the appender has been turned off. This is useful for appenders that write data to a remote location (such as syslog or email), and that write encounters too many errors. The appender can turn itself off to and log an error via the `Logging` logger.
Set the appender’s level to a valid value to turn it back on.
312 313 314 |
# File 'lib/logging/appender.rb', line 312 def off? @level >= ::Logging::LEVELS.length end |
#reopen ⇒ Object
Reopen the connection to the underlying logging destination. If the connection is currently closed then it will be opened. If the connection is currently open then it will be closed and immediately opened.
239 240 241 242 |
# File 'lib/logging/appender.rb', line 239 def reopen @closed = false self end |
#to_s ⇒ Object
call-seq:
to_s => string
Returns a string representation of the appender.
262 263 264 |
# File 'lib/logging/appender.rb', line 262 def to_s "<%s name=\"%s\">" % [self.class.name.sub(%r/^Logging::/, ''), self.name] end |