Object
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
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
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
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
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 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
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
Returns the list of appenders.
# File lib/logging/logger.rb, line 312 312: def appenders 313: @appenders.dup 314: end
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
Remove all appenders from this logger.
# File lib/logging/logger.rb, line 369 369: def clear_appenders( ) @appenders.clear end
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
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
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 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
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
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
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
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.