module Loggability
A mixin that provides a top-level logging subsystem based on Logger.
Constants
- AGGREGATE_METHODS
The methods that are delegated across all loggers
- CONFIG_DEFAULTS
Configuration defaults
- GLOBAL_KEY
The key for the global logger (Loggability's own logger)
- LOGSPEC_PATTERN
Regexp for parsing logspec lines in the config
- REVISION
VCS revision
- VERSION
Package version constant
Attributes
Public Class Methods
Cast the given device
to a Loggability::Logger, if possible, and
return it. If it can't be converted, raises a ArgumentError.
# File lib/loggability.rb, line 71 def self::Logger( device ) return device if device.is_a?( Loggability::Logger ) return Loggability::Logger.from_std_logger( device ) if device.is_a?( ::Logger ) return Loggability::Logger.new( device ) end
Return the Loggability::Logger for
the loghost associated with logclient
.
# File lib/loggability.rb, line 110 def self::[]( logclient ) key = self.log_host_key_for( logclient ) key ||= GLOBAL_KEY loghost = self.log_hosts[ key ] or raise ArgumentError, "no log host set up for %p yet." % [ key ] return loghost.logger end
Clear out all log hosts except for ones which start with '_'. This is intended to be used for testing.
# File lib/loggability.rb, line 122 def self::clear_loghosts self.log_hosts.delete_if {|key,_| !key.to_s.start_with?('_') } end
Returns true
if there is a log host associated with the given
object
.
# File lib/loggability.rb, line 103 def self::log_host?( object ) key = self.log_host_key_for( object ) or return false return self.log_hosts.key?( key ) end
Return the log host key for object
, using its log_host_key
method if it has one, or returning it as a Symbol if it responds to to_sym.
Returns nil
if no key could be derived.
# File lib/loggability.rb, line 95 def self::log_host_key_for( object ) return object.log_host_key if object.respond_to?( :log_host_key ) return object.to_sym if object.respond_to?( :to_sym ) return nil end
Register the specified host
as a log host. It should already
have been extended with LogHostMethods.
# File lib/loggability.rb, line 80 def self::register_loghost( host ) key = host.log_host_key if self.log_hosts.key?( key ) self.logger.warn "Replacing existing log host for %p (%p) with %p" % [ key, self.log_hosts[key], host ] end self.logger.debug "Registering %p log host: %p" % [ key, host ] if self.logger self.log_hosts[ key ] = host end
Return the library's version string
# File lib/loggability.rb, line 62 def self::version_string( include_buildnum=false ) vstring = "%s %s" % [ self.name, VERSION ] vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum return vstring end
Aggregate Methods
↑ topPublic Class Methods
Call the method with the given methodname
across the loggers
of all loghosts with the given arg
and/or block
.
# File lib/loggability.rb, line 133 def self::aggregate( methodname, arg, &block ) # self.log.debug "Aggregating a call to %p with %p to %d log hosts" % # [ methodname, arg, Loggability.log_hosts.length ] Loggability.log_hosts.values.each do |loghost| # self.log.debug " %p.logger.%s( %p )" % [ loghost, methodname, arg ] loghost.logger.send( methodname, arg, &block ) end end
:method: ::format_with
Aggregate method: set all loggers to log with the given
formatter
. See Loggability::Logger#format_with
for more info.
# File lib/loggability.rb, line 210 def self::format_with( formatter ) self.aggregate( :format_with, formatter ) end
Aggregate method: set all loggers to log with the given
formatter
for the duration of the block
,
restoring the original formatters afterward. If no block is given, returns
a Loggability::Override object that
will override all formatters whenever its #call
method is
called.
# File lib/loggability.rb, line 223 def self::formatted_with( formatter, &block ) override = Loggability::Override.formatted_with( formatter ) if block return override.call( &block ) else return override end end
:method: level=
Aggregate method: set the log level on all loggers to
newlevel
. See Loggability::Logger#level=
for more info.
# File lib/loggability.rb, line 150 def self::level=( newlevel ) self.aggregate( :level=, newlevel ) end
:method: ::output_to
Aggregate method: set all loggers to log to destination
. See
Loggability::Logger#output_to
for more info.
# File lib/loggability.rb, line 178 def self::output_to( newdevice ) self.aggregate( :output_to, newdevice ) end
Aggregate method: set all loggers to log to destination
for
the duration of the block
, restoring the original destination
afterward. If no block is given, returns a Loggability::Override object that will
log to destination
whenever its #call
method is
called.
# File lib/loggability.rb, line 190 def self::outputting_to( newdevice, &block ) override = Loggability::Override.outputting_to( newdevice ) if block return override.call( &block ) else return override end end
Aggregate method: set the log level on all loggers to level
for the duration of the block
, restoring the original levels
afterward. If no block is given, returns a Loggability::Override object that set
the log level to level
while its #call
method is
being called.
# File lib/loggability.rb, line 159 def self::with_level( level, &block ) override = Loggability::Override.with_level( level ) if block return override.call( &block ) else return override end end
Configurability Support
↑ topPublic Class Methods
Configurability API – configure logging.
# File lib/loggability.rb, line 277 def self::configure( config=nil ) if config self.log.debug "Configuring Loggability with custom config." confighash = config.to_hash # Set up all loggers with defaults first if defaultspec = confighash.delete( :__default__ ) || confighash.delete( '__default__' ) level, format, target = self.parse_config_spec( defaultspec ) Loggability.level = level if level Loggability.format_as( format ) if format Loggability.output_to( target ) if target end # Then let individual configs override. confighash.each do |key, logspec| unless Loggability.log_host?( key ) self.log.debug " no such log host %p; skipping" % [ key ] next end self.log.debug " configuring logger for %p: %s" % [ key, logspec ] level, format, target = self.parse_config_spec( logspec ) Loggability[ key ].level = level if level Loggability[ key ].format_with( format ) if format Loggability[ key ].output_to( target ) if target end else self.log.debug "Configuring Loggability with defaults." end end
Parse the specified spec
into level,
# File lib/loggability.rb, line 310 def self::parse_config_spec( spec ) match = LOGSPEC_PATTERN.match( spec ) or raise ArgumentError, "Couldn't parse logspec: %p" % [ spec ] self.log.debug " parsed config spec %p -> %p" % [ spec, match ] severity, target, format = match.captures target = case target when 'STDOUT' then $stdout when 'STDERR' then $stderr else target end return severity, format, target end
LogClient API
↑ topPublic Instance Methods
Register as a log client that will log to to the given
loghost
, which can be either the key
the host
registered with, or the log host object itself. Log messages can be written
to the loghost via the LogClient
API, which is automatically included.
# File lib/loggability.rb, line 257 def log_to( loghost ) extend( Loggability::LogClient ) include( Loggability::LogClient::InstanceMethods ) if self.is_a?( Class ) self.log_host_key = Loggability.log_host_key_for( loghost ) end
LogHost API
↑ topPublic Instance Methods
Register as a log host associated with the given key
, add the
methods from LogHost, and install a
Loggability::Logger.
# File lib/loggability.rb, line 240 def log_as( key ) extend( Loggability::LogHost ) include( Loggability::LogClient::InstanceMethods ) if self.is_a?( Class ) self.log_host_key = key.to_sym self.logger = self.default_logger = Loggability::Logger.new Loggability.register_loghost( self ) end