Parent

Logging::Logger

The Logger class is the primary interface to the Logging framework. It provides the logging methods that will be called from user methods, and it generates logging events that are sent to the appenders (the appenders take care of sending the log events to the logging destinations — files, sockets, etc).

Logger instances are obtained from the Repository and should not be directly created by users.

Example:

   log = Logging.logger['my logger']
   log.add_appenders( Logging.appenders.stdout )   # append to STDOUT
   log.level = :info                               # log 'info' and above

   log.info 'starting foo operation'
   ...
   log.info 'finishing foo operation'
   ...
   log.fatal 'unknown exception', exception

Attributes

name[R]
parent[R]
additive[R]
trace[R]

Public Class Methods

new( name ) Logger[name] click to toggle source

Returns the logger identified by name.

When name is a String or a Symbol it will be used “as is” to retrieve the logger. When name is a Class the class name will be used to retrieve the logger. When name is an object the name of the object’s class will be used to retrieve the logger.

Example:

  obj = MyClass.new

  log1 = Logger.new(obj)
  log2 = Logger.new(MyClass)
  log3 = Logger['MyClass']

  log1.object_id == log2.object_id         # => true
  log2.object_id == log3.object_id         # => true
     # File lib/logging/logger.rb, line 151
151:     def initialize( name )
152:       case name
153:       when String
154:         raise(ArgumentError, "logger must have a name") if name.empty?
155:       else raise(ArgumentError, "logger name must be a String") end
156: 
157:       repo = ::Logging::Repository.instance
158:       _setup(name, :parent => repo.parent(name))
159:     end
root click to toggle source

Returns the root logger.

    # File lib/logging/logger.rb, line 36
36:       def root
37:         ::Logging::Repository.instance[:root]
38:       end

Public Instance Methods

log << "message" click to toggle source

Log the given message without any formatting and without performing any level checks. The message is logged to all appenders. The message is passed up the logger tree if this logger’s additivity is true.

     # File lib/logging/logger.rb, line 182
182:     def <<( msg )
183:       @appenders.each {|a| a << msg}
184:       @parent << msg if @additive
185:     end
Also aliased as: write
log <=> other click to toggle source

Compares this logger by name to another logger. The normal return codes for String objects apply.

     # File lib/logging/logger.rb, line 167
167:     def <=>( other )
168:       case other
169:       when self; 0
170:       when ::Logging::RootLogger; 1
171:       when ::Logging::Logger; @name <=> other.name
172:       else raise ArgumentError, 'expecting a Logger instance' end
173:     end
add( severity, message = nil ) {block} click to toggle source

Log a message if the given severity is high enough. This is the generic logging method. Users will be more inclined to use #, #, #, #, and #.

Message format: message can be any object, but it has to be converted to a String in order to log it. The Logging::format_as method is used to determine how objects chould be converted to strings. Generally, inspect is used.

A special case is an Exception object, which will be printed in detail, including message, class, and backtrace.

If a message is not given, then the return value from the block is used as the message to log. This is useful when creating the actual message is an expensive operation. This allows the logger to check the severity against the configured level before actually constructing the message.

This method returns true if the message was logged, and false is returned if the message was not logged.

     # File lib/logging/logger.rb, line 212
212:     def add( lvl, data = nil, progname = nil )
213:       lvl = Integer(lvl)
214:       return false if lvl < level
215: 
216:       data = yield if block_given?
217:       log_event(::Logging::LogEvent.new(@name, lvl, data, @trace))
218:       true
219:     end
add_appenders( appenders ) click to toggle source

Add the given appenders to the list of appenders, where appenders can be either a single appender or an array of appenders.

     # File lib/logging/logger.rb, line 333
333:     def add_appenders( *args )
334:       args.flatten.each do |arg|
335:         o = arg.kind_of?(::Logging::Appender) ? arg : ::Logging::Appenders[arg.to_s]
336:         raise ArgumentError, "unknown appender #{arg.inspect}" if o.nil?
337:         @appenders << o unless @appenders.include?(o)
338:       end
339:       self
340:     end
additive = true click to toggle source

Sets the additivity of the logger. Acceptable values are true, ‘true’, false, ‘false’, or nil. In this case nil does not change the additivity

     # File lib/logging/logger.rb, line 228
228:     def additive=( val )
229:       @additive = case val
230:                   when true, 'true'; true
231:                   when false, 'false'; false
232:                   when nil; @additive
233:                   else raise ArgumentError, 'expecting a boolean' end
234:     end
appenders() click to toggle source

Returns the list of appenders.

     # File lib/logging/logger.rb, line 312
312:     def appenders
313:       @appenders.dup
314:     end
appenders = app click to toggle source

Clears the current list of appenders and replaces them with app, where app can be either a single appender or an array of appenders.

     # File lib/logging/logger.rb, line 322
322:     def appenders=( args )
323:       @appenders.clear
324:       add_appenders(*args) unless args.nil?
325:     end
clear_appenders click to toggle source

Remove all appenders from this logger.

     # File lib/logging/logger.rb, line 369
369:     def clear_appenders( ) @appenders.clear end
inspect => string click to toggle source

Returns a string representation of the logger.

     # File lib/logging/logger.rb, line 376
376:     def inspect
377:       "<%s:0x%x name=\"%s\">" % [self.class.name, self.object_id, self.name]
378:     end
level => integer click to toggle source

Returns an integer which is the defined log level for this logger.

     # File lib/logging/logger.rb, line 256
256:     def level
257:       return @level unless @level.nil?
258:       @parent.level
259:     end
level = :all click to toggle source

Set the level for this logger. The level can be either a String, a Symbol, or a Fixnum. An ArgumentError is raised if this is not the case.

There are two special levels — “all” and “off”. The former will enable log messages from this logger. The latter will disable all log messages from this logger.

Setting the logger level to nil will cause the parent’s logger level to be used.

Example:

   log.level = :debug
   log.level = "INFO"
   log.level = 4
   log.level = 'off'
   log.level = :all

These produce an ArgumentError

   log.level = Object
   log.level = -1
   log.level = 1_000_000_000_000
     # File lib/logging/logger.rb, line 289
289:     def level=( level )
290:       @level =
291:         if level.nil? then level
292:         else
293:           lvl = case level
294:                 when String, Symbol; ::Logging::level_num(level)
295:                 when Fixnum; level
296:                 else
297:                   raise ArgumentError,
298:                         "level must be a String, Symbol, or Integer"
299:                 end
300:           if lvl.nil? or lvl < 0 or lvl > ::Logging::LEVELS.length
301:             raise ArgumentError, "unknown level was given '#{level}'"
302:           end
303:           lvl
304:         end
305: 
306:       define_log_methods(true)
307:       self.level
308:     end
remove_appenders( appenders ) click to toggle source

Remove the given appenders from the list of appenders. The appenders to remove can be identified either by name using a String or by passing the appender instance. appenders can be a single appender or an array of appenders.

     # File lib/logging/logger.rb, line 350
350:     def remove_appenders( *args )
351:       args.flatten.each do |arg|
352:         @appenders.delete_if do |a|
353:           case arg
354:           when String; arg == a.name
355:           when ::Logging::Appender; arg.object_id == a.object_id
356:           else
357:             raise ArgumentError, "#{arg.inspect} is not a 'Logging::Appender'"
358:           end
359:         end
360:       end
361:       self
362:     end
trace = true click to toggle source

Sets the tracing of the logger. Acceptable values are true, ‘true’, false, ‘false’, or nil. In this case nil does not change the tracing.

     # File lib/logging/logger.rb, line 243
243:     def trace=( val )
244:       @trace = case val
245:                when true, 'true'; true
246:                when false, 'false'; false
247:                when nil; @trace
248:                else raise ArgumentError, 'expecting a boolean' end
249:     end
write( msg ) click to toggle source
Alias for: <<

Protected Instance Methods

define_log_methods( force = false ) click to toggle source

Define the logging methods for this logger based on the configured log level. If the level is nil, then we will ask our parent for it’s level and define log levels accordingly. The force flag will skip this check.

Recursively call this method on all our children loggers.

     # File lib/logging/logger.rb, line 414
414:     def define_log_methods( force = false )
415:       return if @level and !force
416: 
417:       ::Logging::Logger.define_log_methods(self)
418:       ::Logging::Repository.instance.children(name).each do |c|
419:         c.define_log_methods
420:       end
421:       self
422:     end
log_event( event ) click to toggle source

Send the given event to the appenders for logging, and pass the event up to the parent if additive mode is enabled. The log level has already been checked before this method is called.

     # File lib/logging/logger.rb, line 399
399:     def log_event( event )
400:       @appenders.each {|a| a.append(event)}
401:       @parent.log_event(event) if @additive
402:     end
parent = ParentLogger click to toggle source

Set the parent logger for this logger. This method will be invoked by the Repository class when a parent or child is added to the hierarchy.

     # File lib/logging/logger.rb, line 390
390:     def parent=( parent ) @parent = parent end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.