Class: Logging::Appender

Inherits:
Object
  • Object
show all
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.

Instance Attribute Summary collapse

Instance Method Summary collapse

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



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/logging/appender.rb', line 32

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

#encoding ⇒ Object

Returns the current Encoding for the appender. The default external econding will be used if none is explicitly set.



263
264
265
 
# File 'lib/logging/appender.rb', line 263

def encoding
  @encoding
end

#filters ⇒ Object

Returns the value of attribute filters.



14
15
16
 
# File 'lib/logging/appender.rb', line 14

def filters
  @filters
end

#layout ⇒ Object

Returns the value of attribute layout.



14
15
16
 
# File 'lib/logging/appender.rb', line 14

def layout
  @layout
end

#level ⇒ Object

Returns the value of attribute level.



14
15
16
 
# File 'lib/logging/appender.rb', line 14

def level
  @level
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



14
15
16
 
# File 'lib/logging/appender.rb', line 14

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.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/logging/appender.rb', line 91

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



250
 
# File 'lib/logging/appender.rb', line 250

alias_method :_to_s, :to_s

#add_filters(*args) ⇒ Object

Sets the filter(s) to be used by this appender. The filters will be applied in the order that they are added to the appender.

Examples

add_filters(Logging::Filters::Level.new(:warn, :error))

Returns this appender instance.



180
181
182
183
184
185
186
187
188
189
 
# File 'lib/logging/appender.rb', line 180

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.



289
290
291
292
293
294
295
 
# File 'lib/logging/appender.rb', line 289

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.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/logging/appender.rb', line 66

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( footer = 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.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/logging/appender.rb', line 199

def close( footer = true )
  return self if @closed
  ::Logging::Appenders.remove(@name)
  @closed = true

  flush

  if footer
    footer = @layout.footer
    unless footer.nil? || footer.empty?
      begin
        write(footer)
      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.

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/logging/appender.rb', line 226

def closed?
  @closed
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.



245
246
247
 
# File 'lib/logging/appender.rb', line 245

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.

Returns:

  • (Boolean) 


303
304
305
 
# File 'lib/logging/appender.rb', line 303

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.



234
235
236
237
 
# File 'lib/logging/appender.rb', line 234

def reopen
  @closed = false
  self
end

#to_s ⇒ Object

call-seq:

to_s => string

Returns a string representation of the appender.



257
258
259
 
# File 'lib/logging/appender.rb', line 257

def to_s
  "<%s name=\"%s\">" % [self.class.name.sub(%r/^Logging::/, ''), self.name]
end